New documentation

[silkentrance]

Requirements

High Priority

• testdeck.org domain
• refactoring
• testdeck seeds
• "working" custom jekyll theme

Frontpage(s)

• Frontpage - basic stuff has been done but requires more work

Guides

• Guides/Setup section #5 Guide/Setup - how to set up the various integrations of testdeck and other stuff like assertion/expectation frameworks, mocking frameworks, dependency injection using TypeScript
• Guides/Basics section #7 Guide/Basics - the basics, e.g. declare a suite and declare some tests, also including async tests
• Guides/Nested Suites section #9 Guide/Nested Suites - the fundamentals about nested suites
• Guides/Advanced Suites section #12 Guide/Advanced Suites - suite execution options and modifiers, (static) lifecycle hooks
• Guides/Suite Inheritance section #11 Guide/Suite Inheritance - the fundamentals about suite inheritance, incl. async (static) lifecycle hook chaining
• Guides/Tests section #15 Guide/Tests - standard and async tests
• Guides/Advanced Tests section #17 Guide/Advanced Tests - test execution options and modifiers
• Guides/Parametrised Tests section #18 Guide/Parametrised Tests - test parametrisation, naming, execution modifiers

Contributing Pages

• Contributing pages #26 Coding style
• Contributing pages #26 Reporting Issues
• Contributing pages #26 Pull Requests

UX/Responsiveness

• sidebar stays in view on desktop devices (part of testdeck-jekyll-theme)
• toc stays in view on desktop devices (part of testdeck-jekyll-theme)

Low Priority

General

• footer

Responsiveness

• navbar behaves correctly on mobile devices

Guides

• Guide/Browser Integration - karma, webpack, ...
• Guide/Babel - how to use this with babel
• Guide/Dependency Injection - everything about dependency injection
• anything else?

Reference Pages

• Integration - How to Integrate other test frameworks
• Dependency Injection - how to integrate other dependency injection frameworks

Contributing Pages

• Code of conduct (do we really need this sh*t?)

Support Pages

• Pointers to e-mail/gitter/github/whatnot

---

With the refactoring in #181 being nearly complete, we should think about also a new documentation that supports all of the existing testdeck integrations.

While every package must have its own README.md, this part of the documentation should focus on the integration alone and refer the user to a common set of documents that will reside at the top level of the mono repo. That way we can still make use of the built in github site functionality.

Domain

The current documentation can be accessed via the mocha-typescript.org domain.

A quick look shows that testdeck.org is still available. Maybe we should use this in the future?

testdeck README.md

This documentation should provide the user with information on the available packages and how to participate in the development a/o building things locally, or even provide new integration packages for other test frameworks that we have not considered yet.

testdeck integration package README.md

This documentation should provide the user with information on how to use a specific integration of testdeck, e.g. @testdeck/mocha with their favourite test framework.

From here, pointers will lead the user to more detailed information in the common documentation.

Also, we have to rework the badges (npm/ci/...).

testdeck seed README.md

The seed's documentation should focus on how to get things running with that particular seed. Provides pointers to testdeck documentation.

Common documentation testdeck/docs

We must remove any reference to mocha-typescript or mocha and make this so that it will give the user information on whether a specific testdeck feature is available for a specific integration, e.g. slow is available on @testdeck/mocha but is ignored/not supported on e.g. @testdeck/jest, and so on.

Also, we have to remove the badges from all documents as these will no longer work.

My initial proposal for the structure would be so, e.g. under testdeck/docs/ one can find the following documents

• index.md
  Provides the user with pointers to the existing other documents. Gives an overview over the available features and integrations for the various test frameworks. Some marketing stuff. Also provides links for each integration package on npm and github.
• api.md
  A general overview of the API.
• suites.md
  Focuses on suite declaration alone, including execution modifiers, lifecycle (aka hooks), and suite settings (slow, timeout, ...).
• tests.md
  Focuses on test declaration alone, including execution modifiers, lifecycle (aka hooks), and suite settings (slow, timeout, ...).
• parametrised_tests.md
  Focuses on parametrised test declaration alone, including execution modifiers, lifecycle (aka hooks), and suite settings (slow, timeout, ...).
• generated_suites.md
  Focuses on dynamic generation of suites. Shows how to combine the standard test UI (describe/it) with the object oriented approach.
• dependency_injection.md
  Focuses on dependency injection alone.
• contributing.md
  Focuses on contribution guide lines, e.g. how to file bug reports, make pull requests and thus participate in the development and so on.
• framework_integration.md
  Focuses on how to integrate additional test frameworks with testdeck, based on an existing integration, e.g. mocha.
• di_integration.md
  Focuses on how to integrate additional ioc / dependency injection frameworks, based on an existing integration, e.g. di-typedi

More?

[silkentrance]

Ideas for the API part of the documentation

testdeck API

@suite

SYNOPSIS

interface SuiteSettings {
  slow?: number;
  timeout?: number;
}

@suite
@suite(settings?: SuiteSettings)
@suite.skip
@suite.skip(settings?: SuiteSettings)
@suite.pending
@suite.pending(settings?: SuiteSettings)
@suite.only
@suite.only(settings?: SuiteSettings)

Suite Settings

slow (mocha only)

...

timeout

...

[pana-cc]

testdeck.org is live now.

[pana-cc]

I like how the https://developers.google.com/protocol-buffers/ is organized, maybe I can get similar design of a website using GitHub pages.

[silkentrance]

I like how the https://developers.google.com/protocol-buffers/ is organized, maybe I can get similar design of a website using GitHub pages.

• https://github.com/pages-themes/

• Multiple Content sections on a page jekyll/jekyll#246

I find the front matter approach rather difficult.

The include approach also looks nice jekyll/jekyll#246 (comment)

This looks rather interesting https://gist.github.com/anonymous/bea7d7389b7331bba512.

Since I have done some ruby in the past, I will try give it a shot...

[silkentrance]

I have looked into this a bit and it is possible by using the include approach.

Maybe we can derive a custom theme from https://github.com/BlackrockDigital/startbootstrap-clean-blog-jekyll?

Then we would have all the means required for block based layouts.

[silkentrance]

Atlernatively we could use this as the basis https://github.com/jameshamann/jekyll-material-theme

which I like even more.

[silkentrance]

Here are some more themes

• https://github.com/DigitalMindCH/gridster-jekyll-theme
• https://github.com/Phlow/feeling-responsive
  which is even better than the capture/include approach: https://raw.githubusercontent.com/Phlow/feeling-responsive/gh-pages/_posts/design/2014-09-10-portfolio.md

[silkentrance]

Should we move the docs to a separate repository, e.g. testdeck/testdeck-site.git or just keep them here?

For initial tests I will set up a testdeck-site repository. We can delete that one once we have found the best theme to use.

[silkentrance]

@pana-cc please have a look at the existing site.

While I take credit and blame for the content, I must say that I am not a web designer. So everything that falls into the latter category is to be considered a work in progress. Maybe you know someone who can do better?