ReadTheDocs inventory

[jmertic]

We want to take inventory of all the projects using ReadTheDocs for documentation and put two things in place.

1. Add the user releng-aswf to each RTDs account as a maintainer. This ensures the LF team can access the instance if everyone else is locked out.
2. Use each project's domain name to create a more uniform URL. For example, docs.opencolorio.org vs. opencolorio.readthedocs.io. Any previous *.readthedocs.io domain will be forwarded to the custom domain. For now, we've set the docs subdomain for each project as a forward to their docs page.

Below is the full inventory of docs pages; note for those not using ReadTheDocs, we did our best to forward to the right location; let us know if that needs adjusted.

Project	Vanity URL(s)	Using RTDs	releng-aswf added to RTD account	Custom Domain active for RTDs
OpenRV		Yes	Yes	No
xstudio		Yes	Yes	No
Imath		Yes	Yes	No
OpenColorIO	docs.opencolorio.org docs.opencolorio.com	Yes	Yes	No
openexr	docs.openexr.org docs.openexr.net docs.openexr.com	Yes	Yes	No
openfx	docs.openeffects.org	Yes	Yes	No
OpenImageIO	docs.openimageio.org docs.openimageio.com	Yes	Yes	No
Open Shading Language	docs.openshadinglanguage.org docs.openshadinglanguage.com	Yes	Yes	No
rez	docs.rez-project.com docs.rez-project.org docs.rez-project.io	Yes	Yes	No
OpenTimelineIO	docs.opentimeline.io	Yes	No	No
OpenCue	docs.opencue.io	No	N/A	N/A
OpenVDB	docs.openvdb.org docs.openvdb.io docs.openvdb.net	No	N/A	N/A
OpenAssetIO	docs.openassetio.org	No	N/A	N/A
DPEL	docs.dpel.org	No	N/A	N/A
MaterialX	docs.materialx.org	No	N/A	N/A
RAW to ACES Utility	docs.rawtoaces.com docs.rawtoaces.org docs.rawtoaces.io	No	N/A	N/A

[JeanChristopheMorinPerso]

Rez uses it, see https://rez.readthedocs.io.

[aclark4life]

As does OpenEXR https://openexr.com/en/latest/ FYI @cary-ilm

[carolalynn]

As does OCIO https://opencolorio.readthedocs.io/en/latest/

[lgritz]

OpenImageIO and Open Shading Language both use it: https://openimageio.readthedocs.io https://open-shading-language.readthedocs.io

[garyo]

OpenFX uses it: https://openfx.readthedocs.io

[jmertic]

Hi everyone! Great to see RTDs used so prevalently.

Two things I'd like to put in motion...

1. Add the user releng-aswf to each of your RTDs accounts as a maintainer. This ensures the LF team can access the instance in the event of everyone else being locked out.
2. I'd like to leverage each project's domain name to have a more uniform-style URL. So for example, docs.opencolorio.org vs opencolorio.readthedocs.io.

If everyone could do (1), our team can help on doing (2) for the project. Note the former URLs will redirect to the new domain.

LMK what everyone thinks!

[garyo]

releng-aswf now invited to openfx (https://openfx.readthedocs.io/en/latest/). We have quite a few references to the readthedocs.io URL on the site and in the code, so once it's switched we'll have some work to do (even if it redirects, we'll want to update to the correct URL).

[JeanChristopheMorinPerso]

releng-aswf added as maintainer of rez.readthedocs.io. For the domain name, what do we do with projects which don't have a home page like OCIO have? Rez has https://rez-project.io/ which redirects to our repo, but we don't actively promote that URL...

[jmertic]

For the domain name, what do we do with projects which don't have a home page like OCIO have? Rez has https://rez-project.io/ which redirects to our repo, but we don't actively promote that URL...

It's up to the project; I'd say keep that pointing to the repo and then docs.rez-project.io pointing to the docs. But we could also have the root domain forward to the docs subdomain too.

[lgritz]

releng-aswf added as maintainer for openimageio and open-shading-language.

I like the idea of making docs.openimageio.org work, but I hope that in the process we can still let openimageio.readthedocs.org work or redirect or something, because there are a lot of docs and old releases that publicize the old address, we've used it for years.

For OSL, I don't care, because our switch to RTD is recent and perhaps still experimental, so I don't think there is any significant switching cost to using a different URL going forward.

[cary-ilm]

OpenEXR uses readthedocs for the entire https://openexr.com website, since pretty much everything we have is documentation. It's fine to have docs.openexr.org redirect, but I'd prefer to keep the site as is, so the documentation pages show up under openexr.com.

I'm open to another configuration, but when I pondered this a while back, I really didn't see a great benefit in drawing a distinction between the "website" and the "documentation". I had a hard enough time sorting out the distinction between the website and the repo markdown.

[reinecke]

OpenTimelineIO is using readthedocs here: https://opentimelineio.readthedocs.io/en/stable/

@jminor @ssteinbach - I may not actually be setup to admin the RTD project, could one of you address the ask from @jmertic?

[jmertic]

I like the idea of making docs.openimageio.org work, but I hope that in the process we can still let openimageio.readthedocs.org work or redirect or something, because there are a lot of docs and old releases that publicize the old address, we've used it for years.

Yep @lgritz - it will keep the old URL and redirect to the new one.

[jmertic]

OpenEXR uses readthedocs for the entire https://openexr.com website, since pretty much everything we have is documentation. It's fine to have docs.openexr.org redirect, but I'd prefer to keep the site as is, so the documentation pages show up under openexr.com.

I'm open to another configuration, but when I pondered this a while back, I really didn't see a great benefit in drawing a distinction between the "website" and the "documentation". I had a hard enough time sorting out the distinction between the website and the repo markdown.

I think that makes sense - it would be good to have docs.openexr.com work as a valid subdomain just for the convention, but completely good with it redirecting to openexr.com. I think the biggest thing is I'd like to see these fancy domain names we have for everyone's projects put to good use :-).

[tykeal]

Ok, we've accepted invites from openfx, OpenImageIO, Open Shading Language, and rez.

Still waiting to see invites on other projects. Also, please post here when you send the invite. The invitations seem to be going to SPAM for some reason :-/ so I had to go hunting for them.

[jmertic]

Actions:

• Any projects who use ReadTheDocs and haven't added the user releng-aswf to each of your RTDs accounts as a maintainer, please do so and let us know.
• When projects are ready, we will transition to using docs.DOMAINNAME for your project's docs

[carolalynn]

Doug added the releng-aswf account to OCIO's RTD account.

[cary-ilm]

I added releng-aswf to OpenEXR and Imath

[tykeal]

Thank you @carolalynn and @cary-ilm we've accepted those invites.

[jmertic]

Hi! I've updated the ticket description to track progress. Actions:

• @reinecke can you help provide access to the OpenTimelineIO ReadTheDocs? Or @tykeal if it is done please add me to that repo as well.
• @cary-ilm @carolalynn @lgritz @garyo @JeanChristopheMorinPerso @erikstrauss let me know if you have concerns with me setting up the docs. subdomain for your project.

Thanks everyone!

[jmertic]

Closing - projects can reach out to have the RTD domains updated if desired.