Mkdocs-based documentation

[thejcannon]

I'm experimenting with mkdocs-based documentation generation to replace our readme-based documentation hosting.

The current running demo:

• Repo: https://github.com/thejcannon/pants-docs
• Docs: https://pants-docs.readthedocs.io/en/latest/introduction/welcome-to-pants/

Why

Getting off Readme

The Readme-based documentation has several limitations:

• The Markdown support is somewhat provisional. Frequently a Markdown-compatible change breaks the documentation
• Users suggest edits in the web UI, which we then have to propagate back
• We pay real dollars per month for a service we could easily not pay for

Mkdocs

• Mkdocs builds on Markdown, which we already have. So porting is mostly scriptable
• It is well-supported. (See the mkdocs-material sponser list: https://github.com/squidfunk/mkdocs-material)
• There are several plugins, with the ability to make your own. See https://github.com/mkdocs/catalog
• It is supported by readthedocs. https://readthedocs.org/

What

Required goals

• All existing links to pantsbuild.org remain (within reason) (ideally with anchors)
• Ability to fully incorporate the generated reference docs
• Docs versioning (e.g. supported docs for 2.14, 2.15, etc...)
  • This doesn't have to be supported at a mkdocs level if we decide to also use a docs host site with support (i.e. readthedocs's support: https://docs.readthedocs.io/en/stable/versions.html)
• Flexible doc structure
  • (Intrinsic to mkdocs)
• Cross-referencing
  • Ideally with validation.
• navbar

Nice-to-haves

• Suggested edits:
  • content.action.edit in the theme features
  • Sends user to the GitHub /edit page for the source page
• "View the source of this page"
  • content.action.view in the theme features
  • Sends user to the GitHub /raw page for the source page
• Multiple slugs for the same page
  • Can use a static set of redirects
• Ability to bundle for offline access
  • mkdocs build + https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/

[thejcannon]

So, for those interested I'm going to spike on also trying out https://docusaurus.io/

It's much more "involved" (you have a full TS/React project instead of just markdown), but I really like the UI/UX better, and the full-customization is pretty nice to have. It may be that the complexity isn't worth it, but I suspect we can fuzz our eyes at a lot of the project-y boilerplate and focus on the content and we'll be OK.