Skip to content
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

Open
jmunroe opened this issue Sep 9, 2023 · 3 comments
Open

RTD Subprojects for centralized search/index of documentation #190

jmunroe opened this issue Sep 9, 2023 · 3 comments

Comments

@jmunroe
Copy link
Contributor

jmunroe commented Sep 9, 2023

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:

  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

on splitting documentation into multiple site for different personas.

@jmunroe
Copy link
Contributor Author

jmunroe commented Sep 9, 2023

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 !

@jmunroe jmunroe changed the title Need for centralized search/index for documentation RTD Subprojects for centralized search/index of documentation Sep 9, 2023
@jmunroe
Copy link
Contributor Author

jmunroe commented Sep 9, 2023

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
Copy link
Contributor

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!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants