Add Fast Mode for Documentation Builds

[talatuyarer]

Every time we build the docs, the mkdocs-monorepo-plugin rebuilds all 14+ versioned documentation of projects even though these old versions never change. This makes iterative development very slow.

I created A development mode that only builds nightly and latest versions to make builds are fast. The production mode still builds all versions which means slow :)

Based on my machine performance it makes 5x more faster. --dirty flag makes even faster iterative rebuilds

How to use

Dev Mod

cd site
make serve-dev  # Only builds nightly + latest

Full production mode

cd site
make serve      # Builds all 14 versions (use before PRs)

Closes #14124

cc @kevinjqliu @RussellSpitzer

[kevinjqliu]

Thanks for working on this. I had to take some time to understand mkdocs' behavior.

Feels like we're on the right path here. From my understanding, there are 2 major issues with building docs locally:

1. nav.yml references all previous versions of the docs
2. mkdocs automatically load all directories inside docs/docs/ and docs/javadoc/

We can resolve (1) by overriding the nav component. We can resolve (2) by using exclude_docs to exclude all other versions.

I tested this out locally and was able to get build done in ~45 seconds.
Instead of replacing nav.yml (which is error-prone imo), I created a new mkdocs-dev.yml and references it in serve-dev.sh

I can push up my local changes if you want to take a look

[kevinjqliu]

@talatuyarer pushed up some of my local changes, as we discussed offline.

Please take a look and see if this is also working for you locally 😄

[kevinjqliu]

INFO - Documentation built in 9.59 seconds

supa fast!

[kevinjqliu]

LGTM!

so much faster now

[kevinjqliu]

Thanks @talatuyarer !

[manuzhang]

I'm wondering whether we can avoid copying other parts of mkdocs.yml. It will be easier to maintain.

[kevinjqliu]

agreed, this is more of a short term solution. both nightly and latest are just sym links to the actual "latest version" (1.10).

long term i want to explore using mike for versioning