#20140 Documentation Porting - Take 2 New discussion created by thejcannon Alright, so as a follow up to https://github.com/pantsbuild/pants/discussions/19553, docs porting is still something I'm working towards, and closer than ever, however it won't be mkdocs-based. Introducing Docusaurus. Why Docusaurus? • It has a much nicer UI/UX docs-side • It provides a very large amount of flexibility in rendering, but also allows markdown. You choose your comfort level • It's well-supported Overall Strategy

main

main

will always contain the support files and "evergreen" pages (list of maintainers, sponsorship info, etc...). Additionally, it will contain the docs for the version

main

represents. release branches Release branches will have the docs included and some (namely release branches made after this switch) will include now-obsolete support files and "evergreen" pages. Local builds Anyone will be able to run

npm start

in the docs directory to run a local hot-reloading version of the docs site. Versioning We can choose between docs-host-versioning and tool-versioning. In order to support "evergreen" pages, and cohesive UI/UX for version selection, the tool-versioning seems most attractive. (Here's Docusaurus' docs: https://docusaurus.io/docs/versioning) Note that the tool doesn't fit our use-case well. Each copy of the versioned docs has to live in the same tree. That would mean naively, all versions of our docs would live on

main

. Therefore, instead we'd need a "build" process when publishing the full docs that would look something like: 1. checkout

main

2. version it accordingly 3. checkout the relevant subtree of

main~1

into the docs dir 4. version it accordingly 5. ... rinse and repeat back to v2.0 Reference docs The "reference" docs are generated from running

help-all

in the Pants repo with a specified set of plugins enabled. That means the above process will need sub-steps to run

pants help-all

to first generate the reference docs for that branch, then version and move on. Blog Docusaurus supports having a blog, so the plan is to port it because it's feeding two birds with one scone. pantsbuild/pants