I'm thinking about the reference docs on the new docs site. (reference docs are the ones generated for each target/subsystem/etc...) Background: • The way docusaurus will work, we'll likely build our docs my smushing together the docs content for each branch from v2.0 up • This will be done at "docs build" time (ideally every push to a release branch and main, too) (also ideally to every PR thats "relevant") Because of the way this'll work, it's prohibitively expensive to try and generate the same reference docs over and over. So, how would we feel about having the reference docs be checked in along the normal docs? Tooling would be in place to help generate it, and a test will exists to ensure the disk contents are legit. This also isn't unlike our github actions generation. Pros: • Docs build is simple and fast • Running docs locally means you see the reference docs too • No dead links Cons: • Generated content in repo • Have to remember to run the command

I’m not averse to checking this in, but I’m curious as to what makes the ref doc generation prohibitively expensive? does it take a very long time to generate?

Yeah. It involves running

pants help-all

. That not only requires compiling the engine (🤮 ) but that command itself takes several seconds to run (even if someone how the engine was cached). THEN you actually generate the content 😕

can’t we cache the help all output from the regular workflow where we run tests and stuff, and pull that down for the docs job?

Possibly? But I would likely suspect the amount of custom tooling involved, and the lack of local-friendly-ness would make it overall a bad idea

I can see this being local-friendly too… using GHA cache tasks there’s not much extra custom tooling involved compared to what would be needed any way (the content generation from the help-all data)

Having to pull every 2.x version and rebuild the world to maintain the website seems like a nonstarter to me? (Eg what if we want to change the doc build format? Will we have to backport changes to all branches?) What’s the reasoning for that?

The docs contents from the earlier branches get rolled up in the build process during the "full" website build. The build config/format itself always comes from

main

(or more precisely whatever branch you're on) The overall user experience of having the tool itself (docusaurus, but same goes for mkdocs-material) manage versions is superior to host-provided versioning. Save for the technical impact, where each version needs to exist pre-build

it’s meant as pseudo code 🤣

(for "dead" branches, I think we ought to check the contents in either way. so consider this thread for "live" branches)

cached for a particular git sha..

Ah, I see. I guess I was expecting something like: 1. Pants repo build is focused on producing a bunch of HTML files for the current code (including internal link validation etc.), without interacting with anything external (including other versions of Pants) 2. Release process uploads those to a hosting provider somehow (potentially just an S3 bucket, e.g.

<s3://docs.pantsbuild.org/2.34.5.dev6/>...

for the

2.34.5.dev6

release) 3. Separate processing (either maintained by us, or from the hosting provider) injects the cross-version functionality, like version selector and redirects for latest

Number 1 is correct, except it builds the code for all versions. It just so happens there's only one version. During build tine pre-pubkish we stitch all branches together, under their respective version. The process results in one set of html files for the whole site. All versions.

Maybe you are suggesting that we do steps 1 and 3 together in the pants repo, as part of the release process?

That seems orthogonal to the generated docs discussion? There's literally one thousand ways we could do docs, I don't want us spending so much time discussing all the possible ways, and losing focus of the MVP for the task at hand of simply getting off readne

I don't think it's orthogonal unless we're only focusing on "how do we create HTML files for a single pants version?", and I don't think we are.

🎉 https://github.com/thejcannon/pantsasaurus So "build a single version" is

npm build

Sorry, I have minimal details of your overall plan, and so am thus having to imagine how it might work, and I've clearly filled in the gaps wrong. Concrete code like that repo is helpful. Thanks.

We're already going to have to commit files to those branches, if we want those branches to have docs.

I'm not sure I follow. If we treat the docs as a built artefact stored outside the repo, we can backfill those artefacts however we want (similar to how we didn't have to commit anything to 2.0.x (etc) have github releases all the way back to 2.0.0)

FWIW Soon (hopefully by the end of the week) I'll have it wired up to be fully versioned as proposed

If we treat the docs as a built artefact stored outside the repo,

(Or, at least, the files that are inputs to the doc building process, whether rendered HTML or md)

That could maybe work, but it'd be yet another process on top of docs creation, and that's kinda what I'm hoping to avoid. I'm also trying to avoid S3 or any other system that involves a credit card 🙂 The docs coming straight from the branches is easy and intuitive (since the version displayed on the docs site is a branch name, not a release name). I also don't feel like we've really discussed at all the proposal at hand, and only discussed ways to avoid it 😕

(Could be GitHub releases rather than S3. Acknowledged.) I am discussing the proposal by saying I’m not a huge fan of committing this generated code, and offering alternatives.

oh, I didn't get this from the beginning, you mean that we would need to run

pants help-all

for each branch we want to document? Then yea, it feels really wasteful to re-run that on every doc publish for all the historic versions knowing that they will be the ~same every time. Checking this in feels like a good move, but perhaps have a dedicated repo for the generated docs that is a wash that is more temporary and doesn't bloat the main pants repo?

So in addition to "check in or not check in" I suppose we can also (continue to) discuss a third option, which is "store the generated markdown somewhere". It's certainly more attractive than generating each time. The easiest would be making a "docs" release from a tag we push whenever we want a new version. We'd have to invent some kind of scheme for that (or maybe we could keep pushing the same tag to the branch?) Comparing it to the above pros/cons: • ✅ Docs build is still (mostly) simple and fast • ❌ Running docs locally means you dont see reference docs • ❌ dead links • ✅ no generated content in repo • ✅ dont have to remember to run anything • ❌ reference docs lag behind in-repo docs ◦ E.g. you can't link to a reference doc item when making docs changes until we release those docs

what does "running docs locally" mean?

npm start

->

localhost:3000

what if the

npm start

is run off of the

docs-repo

where we have all the reference docs material generated into.. ? then it would contain everything, right?

Trying to maintain a shadow-repo isn't likely to be an easy task IMO. It also might confuse folks

I think "folks" shouldn't generally need to be aware of it..

❌ Running docs locally means you dont see reference docs

I don't understand this. If we have a process for "create and store the geneated markdown somewhere", can't the process to create that markdown feed into running the docs locally?

❌ dead links

Why does this follow?

❌ reference docs lag behind in-repo docs

This seems correct? It seems undesirable to have the published reference docs ahead of actual releases. Sometimes it'll just be some text changes that could go out early, but often it'll be more than that (new fields etc.)

1. Yes, but you'd have to run that process before

npm start

to see the reference docs 2. Any docs links to reference docs will be dead 3. I was thinking more about changes locally. E.g. I want to make a PR to the

docs/

and need to link to the field. But essentially it's just another flavor of "dead link"

> Yes, but you'd have to run that process before

npm start

to see the reference docs Ah, I was assuming anything in the Pants repo would be run via pants itself and thus be able to depend on codegen targets. (I think technically we could also have

npm start

have a

prestart

script that calls pants too) > Any docs links to reference docs will be dead As in, for the files stored in the repo,

[text](reference-blah)

will look broken for source-code-only analysis? If we have a tool that can check dead links for us (is that what you're thinking?), could it hook into the codegen target above too to have all files available? > I was thinking more about changes locally. E.g. I want to make a PR to the

docs/

and need to link to the field. But essentially it's just another flavor of "dead link" Hm, not sure what you mean, but okay, I'll assume solving dead links solves this.

Can we check it in to a different sidecar repo?

So given that among this third option there are two options, which do people prefer? • Sidecar repo • GitHub Releases for docs

I’m +1 to a “sidecar” repo. Using releases feels like it would clutter up the space where users go to find regular pants releases..?

Naive Clarifying Question: I have the most experience with Git*Lab* pages which don't support any of the important versioning requirements here and have a really simple "make html however you want and upload it $HERE" model. Is that... not how readthedocs and docusaurus work? They need to be able to "build" each branch/tag on the fly?

There's moving pieces, for sure. Maybe I'll do a write up soon and make (another) GitHub Discussion. GitHub has the same "upload HTML here plz" and, of course, leveraging GitHub Actions it's all autonomous. Thats' GitHub Pages Then, you need to build that HTML from markdown. That's

mkdocs

and

docusaurus

. The hard part for us is two-fold: • We have generated docs --> reference docs which are generated (we can choose to generate either html or markdown) from

pants help-all

• We want to maintain docs for over a dozen versions. Albeit some are "dead". Those are where the challenge lies. Docs hosters (like readthedocs, and readme) offer "let us handle the versioning for you". That's a huge pro for the multiple-versions thorn. But is also is a con, because "evergreen" docs are now versioned, and you usually are getting a shittier UI/UX when it comes to versioning. We could use the tools' versioning scheme which means everything stays in ecosystem, but that means we need all of the docs (going back to every version) at build time. The big pro is you get one complete docs site (meaning you could go as simple as GitHub Pages). If there was a way in-tool to do a partial build (mkdocs maaaayyyybe has one, but I'm leaning heavily on docusaurus) this would be mostly a nonstarter. Maybe I'll ask around

Thanks for the context. And I suppose the fundamental bit I'm missing is: " let us handle the versioning for you" doesn't take the form of "upload your v1.2.3 HTMl to the v1.2.3 subdir" but something more all encompassing?

"let us handle the versioning for you" is more, send us the HTML for this version. It's now a snapshot. Similar to what we have today.Albeit for the cheaper/free-er options the UI/UX gets worse than what we have today. And we still have the problem of versioned "evergreen" docs. (e.g. service providers, list of maintainers)

Maybe I'll do a write up soon and make (another) GitHub Discussion

Yeah, this'd be helpful; as it is, I think we're trying to evaluate/provide feedback on a small piece of a larger plan, without seeing the larger plan 🙂

I'm realizing now that we dont have to compile the engine to run

help-all

because we're asking for

help

on plugins baked into Pants itself. That changes things I think... This whole thing might be moot, as that doesn't feel prohibitively expensive...

I’m realizing now that we dont have to compile the engine to run

help-all

because we’re asking for

help

on plugins baked into Pants itself. That changes things I think...

I don’t think all iterations of backends is compatible with any one version of the engine… 😕

We're only ever running already-released (read: already compiled Pants) on an invocation with an essentially empty Pants project, with a subset of the already-embedded backends enabled. Therefore, it really is plug-and-play. Does that makes sense?

ah, yea, you mean for older versions we merely download the released pex and get the help-all from that

Funny enough, it actually is pretty fast to run

help-all

in a loop over all the versions, lol