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

Test RTD subprojects #129

Open
mjherzog opened this issue Jul 19, 2023 · 9 comments
Open

Test RTD subprojects #129

mjherzog opened this issue Jul 19, 2023 · 9 comments

Comments

@mjherzog
Copy link
Member

We need to determine whether / how to use AboutCode as a top-level site/directory for all of our project documentation. The Subprojects feature - https://docs.readthedocs.io/en/stable/subprojects.html - may support this, but it is not clear how it works and how much it would impact the structure and operation of the RTD pages for subprojects like SCTK, SCIO, etc.
I think that we are looking for something that would allow us to easily maintain a directory of links to the various projects with minimal impact on how we manage the doc for each subproject.
I propose that aboutcode-toolkit would be a a good project to test with.

@AyanSinhaMahapatra
Copy link
Collaborator

This seems doable, the sub projects don't have any impact on the doc management of each project it seems, it's just like a custom link. I tried out the guide here https://docs.readthedocs.io/en/stable/guides/subprojects.html too.

Btw,

[How to link to other documentation projects with Intersphinx](https://docs.readthedocs.io/en/stable/guides/intersphinx.html)

    Learn how to use references between different Sphinx projects, for instance between subprojects

We already use this ^ to link some projects, we can start using this more extensively too.

@AyanSinhaMahapatra
Copy link
Collaborator

@mjherzog
Copy link
Member Author

@AyanSinhaMahapatra I am not sure what I should be looking at

@AyanSinhaMahapatra
Copy link
Collaborator

AyanSinhaMahapatra commented Jul 21, 2023

The aboutcode-toolkit project is now set as a subproject of the main aboutcode RTD, see the main page above, which is https://aboutcode.readthedocs.io/, and it has then the subpath projects/aboutcode-toolkit/en/latest/ which then has the aboutcode-toolkit docs inside, and this has no impact on how we manage the doc for each subproject.
Just a way to host these docs togehter, this is how the subproject feature works.
Just testing this out, is this what we wanted?

@mjherzog
Copy link
Member Author

That is what I was hoping to see, but I do not see aboutcode-toolkit from the top aboutcode.readthedocs.io. I cleared my cache but still so not see it (?)

@AyanSinhaMahapatra
Copy link
Collaborator

AyanSinhaMahapatra commented Jul 21, 2023

I do not see aboutcode-toolkit from the top aboutcode.readthedocs.io

We can do so by adding links to the aboutcode-toolkit docs explicitly there. As required, both in the left side panel and the landing page. This is not done automatically by adding the subproject (but could have been nice if it happened).
Shall I add that?

@mjherzog
Copy link
Member Author

I am still unclear about what I was supposed to see on the AboutCode page. We currently have the https://aboutcode.readthedocs.io/en/latest/aboutcode-project-overview.html page which lists some of our projects but I think that this was created manually. Please go ahead and add aboutcode-toolkit as a subproject so that we can see how it looks.

@AyanSinhaMahapatra
Copy link
Collaborator

Please go ahead and add aboutcode-toolkit as a subproject so that we can see how it looks.

I already had 😛
That's why we have https://aboutcode.readthedocs.io/projects/aboutcode-toolkit/en/latest/, which mirrors the RTD we had at https://aboutcode-toolkit.readthedocs.io/en/latest/ earlier, and if you visit this https://aboutcode-toolkit.readthedocs.io/en/latest/, you see that you are instead redirected to https://aboutcode.readthedocs.io/projects/aboutcode-toolkit/en/latest/. The aboutcode-toolkit RTD doesn't exist as a standalone anymore.
Also see the screenshot below, this RTD is the aboutcode RTD, and aboutcode-toolkit is also added here because it's added as a sub-project.

I also added PURLdb, just for you to check, as an example: https://aboutcode.readthedocs.io/projects/PURLdb/en/latest/
If you go to purldb.readthedocs.io, you will also be redirected to https://aboutcode.readthedocs.io/projects/PURLdb/en/latest/, and so the purldb.readthedocs.io does not exist as a standalone too anymore.

This is the only thing that happens when you add a subproject.

aboutcode-doc-subproject

I'm not sure I get what you're looking for otherwise, it seems this was not what you were looking for in the subprojects features?

@mjherzog
Copy link
Member Author

I was hoping that Subprojects would make it easier to maintain a TOC or index of our projects on the AboutCode page, but it seems that all it does is change the URL to nest the projects under /aboutcode.readthedocs.io/projects/ - which is good and should be helpful for admin related to our subprojects, but does not directly help with how we present AboutCode projects from a user perspective.
I think that we should proceed to move all of our projects to subprojects for the admin/mgt improvement.
We will need to do separate work to set up a TOC or index from AboutCode to all of our projects.

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

No branches or pull requests

2 participants