New documentation #4
Description
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?