-
Notifications
You must be signed in to change notification settings - Fork 17
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
RTD Subprojects for centralized search/index of documentation #190
Comments
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):
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 ! |
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. |
I have not used the RTD subproject feature before and I would not be against it, I think. |
Our 'Documentation ' is made up of three separate sources of documentation sites:
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:
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
on splitting documentation into multiple site for different personas.
The text was updated successfully, but these errors were encountered: