Shared table of contents across all nextstrain read the docs projects

[eharkins]

We achieve #3 using git submodules; see https://github.com/nextstrain/docs.nextstrain.org/tree/migrate#submodules

However, this solution is not ideal; see https://bedfordlab.slack.com/archives/C7SDVPBLZ/p1602020878007600

So, we also use Read The Docs subprojects; see https://github.com/nextstrain/docs.nextstrain.org/tree/migrate#how-we-are-currently-using-subprojects

This issue is a placeholder for a "best of both worlds" approach, which is currently being pursued by @trs:

A subprojects + shared/global table of contents approach is preferred to the current subprojects + submodules + separate table of contents approach.
I'll carve a few days out to finish implementing this, and at the same time, James and Eli will continue to push forward with their remaining tasks. We'll see how timing of the completion of both coincides and make a decision to either launch docs.nextstrain.org with the current approach or use the new approach depending on if the new approach is ready.
If the launch happens with the current approach, then we can switch approaches later, just with a bit more tedium.

For more discussion on that, see https://bedfordlab.slack.com/archives/C7SDVPBLZ/p1602626783056100?thread_ts=1602622975.053700&cid=C7SDVPBLZ

[eharkins]

In #36 we move from a submodule approach to a fetching approach where we make a request for a page from it's github URL. Importantly we still hope to replace that approach with the approach mentioned here: a shared table of contents across nextstrain read the docs projects.

[tsibley]

Some notes to self on prior art I recently stumbled across that's new to me:

• http://www.virtualroadside.com/blog/index.php/2017/01/14/integrated-subproject-sites-on-readthedocs-org/
• What's your experience using this? DriesSchaumont/sphinx-subprojecttoctree#65

[tsibley]

and also for posterity, my original investigation for this (~2.5yrs ago) primarily resulted in some Sphinx code diving and discussion in sphinx-doc/sphinx#1836.

[victorlin]

I'm out of the loop here and have a couple questions:

1. Given that all the projects have pretty different TOCs, what would a shared TOC look like?
2. Is this the only solution to stop fetching docs from other repositories?

[tsibley]

The original idea was that you could browse/read the subprojects without losing access to the umbrella project's sidebar/search. For example, if you click on "Nextstrain CLI" from the umbrella project:

You end up with a wholly different sidebar. This can be a bit disorienting. To switch to the Augur docs, for example, you have to go back to (resurface in) the umbrella project and then dive back down again. Disorientation can also crop up via search. If you search in the umbrella project, you get search across all projects. That's a good thing! But if you click into a result for Augur, you're then siloed there until you pop back up to the umbrella project.

[tsibley]

A shared TOC could look like "Nextstrain CLI" and those other components above being headings with pages beneath them, like other bits of the umbrella project.

It's not the only solution to not fetching docs across repos. But regardless of whether we fetch or not, a shared TOC would make for a less disorienting/fractured experience.

[victorlin]

+1 for a solution here which I'm assuming will also solve the cross-searching problem. I just took a look at the Nextstrain CLI docs search analytics and these are the top queries from the past 30 days:

Lots of "0 results" which could benefit from the ability to search across projects.

[tsibley]

Lots of "0 results" which could benefit from the ability to search across projects.

We have cross-project search on the umbrella project, but the project-scoped sidebar is again tripping us up here.

[victorlin]

Yes, I should have said "ability to search across projects from any docs page".