RTD Subprojects for centralized search/index of documentation

[jmunroe]

Our 'Documentation ' is made up of three separate sources of documentation sites:

• Hub Service Guide: https://docs.2i2c.org/ (RTD)
• Infrastructure Guide: https://infrastructure.2i2c.org/ (RTD)
• Team Compass: https://team-compass.2i2c.org/ (RTD)

I understand that this are for different audiences so I think I see why they are created separately. However, as a member of all of the audiences I often find myself doing:

1. Is this 'thing' (whatever I am thinking about at the time) already in our docs?
2. Which set of documentation is it in?
   • Search in docs .... get a few links
   • Search in infrastructure ... get a couple more
   • Search in team-compass ... find something else.
3. Inevitable confusion on my part on which documentation site I am actually in.

I am reading about the readthedocs subprojects feature as a way of solving my confusion. Has subprojects already been explored by someone at 2i2c?

I notice that we have an open issue on a related but different issue

• Split this documentation into a monorepo with multiple sites #126

on splitting documentation into multiple site for different personas.

[jmunroe]

Well that was surprisingly simple. As a proof of concept, I create a RTD template repo : https://github.com/jmunroe/2i2c

and imported that as as RTD project: https://readthedocs.org/projects/2i2c/ (no change at all to the template site)

Then I am imported three new RTD projects based on forks of our documentations sites (I am hesitant about breaking anything on our 'real' repos so didn't want to touch them):

• https://readthedocs.org/projects/2i2c-compass/
• https://readthedocs.org/projects/2i2c-docs/
• https://readthedocs.org/projects/2i2c-infrastructure/

Then using the 'Admin' tools on the https://readthedocs.org/projects/2i2c/ I added compass, docs, and infrastructure as subprojects. The effect to the URLs for host those three projects under there own domain but as paths under the the main project domain:

Example: http://2i2c-infrastructure.readthedocs.io/ -> https://2i2c.readthedocs.io/projects/infrastrucure/en/latest/

The win for me is is now the search on the 'main' site indexes all three subprojects:

Example: https://2i2c.readthedocs.io/en/latest/search.html?q=jupyter

gives search results from compass, docs, and infrastructure !

[jmunroe]

I don't think the required any changes to to the subprojects repos so I probably would have been safe referencing those directly instead of my forks.

When cross linking between these different 'subprojects', RTD recommends Intersphinx links although I think we can continue to use explicit URLs.

I am curious if others have opinions on RTD subprojects and if this is a useful path to continue to pursue.

[damianavila]

I have not used the RTD subproject feature before and I would not be against it, I think.
I am pretty sure @choldgraf will have an opinion about this topic, eager to hear his thoughts!