Documentation Porting - Take 2

[thejcannon]

Alright, so as a follow up to #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.

We'll likely want/need a strategy to not run this process on "dead" branches. Both for the savings in build time as well as complexity (the help-all output likely has and will change, meaning we would need to maintain multiple "generator" templates).

Blog

Docusaurus supports having a blog, so the plan is to port it because it's feeding two birds with one scone.

Existing URLs

I'll generate a sitemap from the existing docs and we can easily host a big redirect script

[thejcannon]

https://github.com/thejcannon/pantsasaurus is my repo demonstrating this.
Here's the docs hosted using GitHub Pages: https://thejcannon.github.io/pantsasaurus/

[huonw]

That looks really nice, well done!

[kaos]

It seems how we do the versioning is the biggest open question?
Could we do a mix?.. I haven't looked yet at what it would imply going with the docs-host-versioning, but I was thinking, if when we build the main docs site, we include the current list of supported/active versions, so that would be perhaps 3-5 stable versions. Older versions than that could be excluded from rebuilds and just sit on a separate "archive" host, more or less frozen in time.
That way we wouldn't have to rebuild all versions back to 2.0 every time, was my idea.. don't know how feasible that is, if at all..

[kaos]

of course, there's permalink considerations to keep in mind as well... (wouldn't want a versions URL to change merely because it dropped out of the current scope of active versions)

[thejcannon]

The main drawback from this is lose the "evergreen" docs staying up to date.

For instance the "service providers" page listing Toolchain. That needed to be scrubbed on every page on every page that lists it. Similarly for the list of maintainers.

The better UI/UX is a benefit 🙂

[tgolsson]

Do we have any statistics on what % of users are on older Pants versions? Is it significant enough to warrant keeping docs for more than say previous/current/next, at most?

[kaos]

I'm a believer of not breaking URLs.. which would imply keeping docs for older versions ~indefinitely.

[tgolsson]

That is a fair point, yeah. In theory that could be solved e.g. by not putting the version in there, something like

• /deprecated/ for previous version
• /stable/ for current version
• /unstable/ for next version

That at least prevents link death, though the contents would change over time as old versions get flushed out.

[kaos]

yeah, and you likely have different pages and subsections and what-not you could potentially link to that would come and go.. 😬

[huonw]

Keeping all versions to avoid breaking permalinks seems like the best case option to me, but maybe it's hard e.g. https://docusaurus.io/docs/versioning#keep-the-number-of-versions-small says specifically "less than 10", I don't know whether that's a docusaurus performance thingy, or a recommendation to avoid overwhelming users or what (hopefully we could at least hide very old versions in selectors, so one just gets to them by direct links).

Another option would be some sort of static web snapshots that aren't rerendered, potentially with a 404 page that dynamically offers a link to the matching one. So, the link is still "broken" (shows different content) but a human can still get to what they were looking for, if they must. The snapshot could be:

• automatic web.archive.org captures (especially if we chuck a few bucks their way) (if the readme pages are acceptably-captured, this might mean we don't even have to migrate old versions off readme)
• some other other sort of HTML snapshot (e.g. the link above talks about netlify doing automatic permalinks, I don't think GH pages does, but conceptually we could implement something like that), along the lines of what @kaos suggested above
• a big old PDF that's autogenerated from the markdown or HTML or something, that's just served as a static file

[huonw]

Thank you for diving into this, it is valuable work. I'm really excited for it!

This scheme seems fairly different to what I'm used to with software that does release branches like Pants. Pants isn't just "constant releases from main" like PEX or scie-pants (this isn't a value judgement, just an observation), and main is the "development branch"... so it seems a bit weird to be having the "prod" website driven off that branch.

For other software that's like Pants that I'm familiar with (for example, Rust, Swift, CPython?), there's typically a split between:

1. generated doc artifacts from the source code itself
   • these are tied to very specific version (e.g. there's a particular version of those artifacts for 2.34.5.dev6, and one for 2.34.5.dev7 etc.)
   • they can be generated in arbitrary complicated ways (e.g. running rustdoc, sphinx etc.)
   • sometimes published to readthedocs (or similar) that manages having a version selector etc., sometimes not
2. one or more separate website repository that contains evergreen docs, blogs etc
   • e.g. https://github.com/python/pythondotorg , https://github.com/rust-lang/www.rust-lang.org , https://github.com/rust-lang/blog.rust-lang.org , https://github.com/apple/swift-org-website
   • even for a static website, the content can be "dynamic" based on the main repo, e.g. automation making updates to auto-generated pages like the various swift-ci commits adding nightly builds in https://github.com/apple/swift-org-website/commits/d01c19f187f6f5e4c66401ec4862dde1405b6e0a/

I imagine we could apply this model to Pants too, e.g.:

1. a pantsbuild.org repository that contains human-maintained evergreen docs and blog
2. a process to extract the requisite doc artifacts from the main repo (i.e. the static markdown + the generated reference pages), and then push to be available to the pantsbuild.org repository
   • (there's various schemes we could decide between here, e.g. committing them straight to main in the right directory, alongside all the human code, or a separate branch that's just the auto-generated stuff that gets checked out in the right place as part of the website generation, or... but either way, this somewhat resolves the conceptual weirdness of having "v2.0 docs on main")

We've been chugging along seemingly okay with manual doc site updates (and no previews etc.) for all releases up to now, so I think we can aim for that bar for MVP of the new process, with a plan for how to improve. That is, the "automation" could be a human running the appropriate command and committing the output to the pantsbuild.org repo. Once we've got those first steps going (and thus migrated off readme), we can start iterating on features like:

• automation
• previews (both locally and in PRs)
• better link checking (we can definitely still do generated-doc link checking, which seems like the most valuable sort, making sure when we link to a reference page (or whatever) the link goes somewhere sensible)

(I don't think we'd be wasting work by staging it like this, we'd just start seeing the benefits sooner without having to solve everything at once.)

What do you think? Can you do a compare-and-contrast of the approaches?

[thejcannon]

It doesn't bother me that main had the evergreen docs, since it's an evergreen branch 😂. But I understand the viewpoint.

---

It never occurred to me to have a sidecar repo with only one branch. That's painfully embarrassing. I love it. I think it'll be the best solution in terms of pros/cons, and means we could roll out immediately when I finish my repo.

The automation would likely be pretty easy too. As would the preview (I hope, that's still TBD).

[thejcannon]

I think the one BIG con is not being able to easily test locally what changes look like.

We don't have that today and we really wish we did.

We can experiment though

[huonw]

Just brainstorming, two options:

1. we could have a (basic) docusaurus config in the pants repo too, for iterating on the generated docs.
2. we could have code that grabs latest docusaurus config from the website repo (e.g. a target, that handles cache invalidation appropriately), so one does something like pants run path/to:docs-preview and automatically see the local docs rendered against the website's current config

Partially duplicated config for 1 obviously isn't great, but, I think it's probably okay:

• I suspect for what one needs for those sort of edits a 100% match with the website isn't required (I imagine the only things that have to match 100% are paths and slug configurations, i.e. parts of the URL that someone might want to paste into some other docs).
• It'll only needs to be a good-enough rendering of the guides and references, not all the ever-green stuff.
• There's an obvious source of truth (i.e. if there's a mismatch, it's the demo config that's wrong)
• A mistake here is reasonably low consequence: if one part of the deployed docs misrender because the demo config was misleading, it's easy enough to patch.

[tgolsson]

Maybe I'm missing the main issue, but one could just have both repos checked out locally, no? Even nesting one in the other if necessary for it to work.

[huonw]

For a website migration, a question that pops up for me is always: will it break existing URLs?

Two comparisons (for ease of comparison, I've replaced thejcannon.github.io/pantsasaurus by www.pantsbuild.org in the displayed text of the first link of each, as I assume that's how the "prod" URLs will end up):

• docs:
  • new: https://www.pantsbuild.org/docs/getting-started/getting-started/prerequisites#linux
  • old: https://www.pantsbuild.org/docs/prerequisites#linux
• blog:
  • new: https://www.pantsbuild.org/blog/2023/08/30/pants-2-17-0-is-released
  • old: https://blog.pantsbuild.org/pants-2-17-0-is-released/

So it looks like we might have some path differences (getting-started/getting-started in docs, and the date in the blog), and domain name differences (pantsbuild.org/blog vs. blog.pantsbuild.org).

I could also imagine the details of some "slug" computations either in paths or fragments might differ in some edge cases (e.g. the various headings on https://www.pantsbuild.org/docs/awslambda-python have punctuation and formatting and numbers, and the fragments for the reference docs often seem to end up bracketed by code, e.g. https://www.pantsbuild.org/docs/reference-_generator_sources_helper#codesourcecode).

What sort of options do we have for smoothing over this change?

[thejcannon]

I forgot to include it in the OP so I'll edit.

I plan on generating a sitemap from every version of the existing docs, and then was going to propose that we maintain a giant redirect script.

[huonw]

Ah, okay, that's a nifty solution. I guess we can have a similar redirect deployed to blog.pantsbuild.org somehow.

[thejcannon]

Yup!

[kaos]

The new docs/blogs sites are now live. 🎉