search

nexB / aboutcode

AboutCode project: tools and data to uncover things about code: the provenance, origin, license, and more (packages, security, quality, etc.) of FOSS code
http://www.aboutcode.org/
154 stars 93 forks source link

Test RTD subprojects #129

Open mjherzog opened 11 months ago

mjherzog commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

See https://aboutcode.readthedocs.io/projects/aboutcode-toolkit/en/latest/ @mjherzog

mjherzog commented 11 months ago

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

AyanSinhaMahapatra commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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 commented 11 months ago

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

I already had :stuck_out_tongue: 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 commented 11 months ago

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.