Handbook built with Sphinx and published on docs.niteo.co #171
Description
The Story
Handbook documents: User story & Work process
As a Nitean,
I want handbook to be ready to publish on https://docs.niteo.co,
so that we have an HTML handbook with a nice theme and can search it easily.
Problem
Currently, we point to GitHub whenever we need to link to the handbook and although this works publishing it on docs.niteo.co would be better with themed HTML generated by Sphinx.
We are also missing checks for spelling, formatting and URLs so by using Sphinx and pre-commit we can solve those issues as well.
Proposal
- Use Sphinx to generate the HTML
- Hyperlinks, both internal and external are checked by Sphinx
- Spelling is checked by Sphinx
- Add pre-commit checks for syntax and formatting issues:
- Fix or warn about trailing whitespace.
- Fix or warn about missing end-of-file newline.
- Use check-symlinks to ensure not broken.
- Perhaps use markdownlint.
Configure and publish the handbook on RTD
Pitfalls
By publishing on docs.niteo.co the handbook would not be available publicly.
Best practices (DoD)
- Documentation is revised:
e.g. help articles, handbook pages, Intra reports or technical docs. - Product users are informed. e.g. blog post on a new major feature.
- Test coverage is 100%.
Expectations (AC)
- Sphinx is being used to generate HTML
- Commit checks for spelling and other formatting issues are enabled.
- Handbook is published on
docs.niteo.co. - User story demo uploaded to Sprint release.