#19553 Mkdocs-based documentation New discussion created by thejcannon I'm experimenting with mkdocs-based documentation generation to replace our readme-based documentation hosting. The current running demo is at: https://thejcannon.github.io/pants/docs 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/ How https://github.com/thejcannon/pants/tree/jcannon/documentation is a branch containing 2 files: • The mkdocs config: https://github.com/thejcannon/pants/blob/jcannon/documentation/docs/mkdocs.yml • A (quick-and-dirty) conversion script: https://github.com/thejcannon/pants/blob/jcannon/documentation/docs/convert.py The idea being that we can automate the migration of the downloadable markdown docs to port to mkdocs 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 ☑︎ Ability to bundle for offline access •

mkdocs build

+ https://squidfunk.github.io/mkdocs-material/setup/building-for-offline-usage/ pantsbuild/pants