readthedocs build time reductions

[aidanfnv]

The builds of the documentation currently take ~29 minutes, intermittently 30-31 minutes.
readthedocs has a 30 minute time limit before they cancel our builds.

The 31 minute builds very rarely get cancelled, though the timer includes time spent cloning the repo and submodules, as well as time spent waiting for the build to start, so ~31 minute builds may be just under 30 minutes in the section that can timeout.

Most of this time is taken up by writing the table of contents to every file, due to how Sphinx works.
Sphinx generates static HTML for every page, so to have links to every page in the TOC from every page in the TOC, those links are written to every file, so build times are O(n²) for n docs pages. This should be fine for a small number of docs, but the Standard Modules Reference has over 1000 markdown files.
Without the Standard Modules Reference, the builds take less than 2 minutes to complete.

[aidanfnv]

One idea that @csyonghe has suggested is to use an iframe to display a single TOC across multiple pages.
That should change the slow part of the building process (writing out the HTML files to disk) from O(n²) to O(n).

Our current build flow for Sphinx (used by readthedocs) goes something like:

• Pre-processing: Uncomment the TOCs, which are commented out to not appear on our existing docs pages
• The actual Sphinx build: Links the TOCs and pages together, and then dumps all of those links to every page
• Post-processing: Not yet relevant to this issue

My proposed new flow to allow the use of an iframe TOC is:

• Pre-processing: Do not uncomment TOCs, instead read and link them in this stage, and at the end of the stage dump the TOC links to a single page
• The actual Sphinx build: No TOCs to link (commented out), renders out the pages to HTML regardless but without the bloat, much faster
• Post-processing: Insert an iframe with the single TOC into each page

Beyond that we would need some scripts to expand the TOC to show the current page and highlight its title in the iframe, to mimic the current TOC sidebar behavior.

[csyonghe]

I am not entirely happy with the way readthedocs handles their TOC scrolling when jumping from page to page anyways, so having our own script to handle loading/highlighitng and scrolling on the TOC seems the way to go.

[csyonghe]

compare.webm

[jkwak-work]

@aidanfnv needs to address the problem Yong pointed out on the video as a next step.
Pushing to the next sprint since @aidanfnv will not be able to work on this until next sprint.