Overview

See the live site here: https://nickcrider.github.io/ot-docs/

Proof of concept for breaking the Opentrons API Documentation into a separate repository written in Markdown instead of reST.

Current implementation uses Material for MkDocs

This has some neat advantages, including:

• Enables separate release cadences for the Docs from the monorepo
• Markdown is easier to use and more portable than reST
• Lowers the bar to contributing/changing the docs
• Modern tools encourage user interaction

Contributing

We love user contributions! See the instructions on how to submit your changes to the docs. While not strictly required, you'll probably want to follow the instructions below to check your work locally before exposing it to the rest of the world.

Setup

Just like the Opentrons Monorepo, you'll need git, pipenv, and make installed. Once you've gotten that taken care of, you can clone the repository, use make to install the dependencies, and then run the development server:

git clone https://github.com/nickcrider/ot-docs.git
cd ot-docs
make setup
make serve

You should now be able to find the docs at http://localhost:8000 the server watches files for changes and automatically reloads

Vale

We're using Vale to automate some simple proofreading tasks and to enforce a style guide. These checks will be run whenever changes are pushed to Github. Using Vale in your development environment is strongly recommended. Once Vale is installed, you can run vale /path/to/file from the repository root. You should also install it as a linter in your IDE (vscode, atom) so the checks are performed automatically as you work.

Notes

See here for a discussion of why the docs use Markdown?

The API reference documentation is generated during the build process from the current version of the opentrons package in PyPi. The process works like this:

1. Sphinx builds the API reference from a reST file using the sphinx-material template.
2. Using Jinja overrides, the output is trimmed to just the main <article> and sidebar content.
3. Scoped CSS is used to override conflicting styles from the two templates (see sphinx/templates/layout.html).
4. The raw HTML generated by sphinx is included in the markdown file and processed by MkDocs

TODO

This is a very early proof of concept. It's more of a playground to explore the organization/function of the docs, while working within the constraints of the authoring tool. It's far from production-ready. Lots of work remains:

• Continue to fine tune semantic organization
• Investigate the possibility of creating automatic links to API reference slugs
• Think about SEO
• Lots of web design stuff
• Get buy in from relevant teams on content & organization