Documentation

[arif-ali]

Hi folks,

One of my key goals over the next year is to improve our documentation, whether it's internal (at Canonical) or external (wiki, rtd, READMEs).

I see by going on the RTD, that the build hasn't passed for 3.5 years (as I was going point to one of the new functions). Who owns that, and is there a way to get that updated so that it builds again and have updated reference for all our functions.

I think we could also potentially combine the Wiki and RTD, so that all the docs is in one place and there's one source of truth.

Thoughts?

[TurboTurtle]

Hazarding a guess that @bmr-cymru is probably the best person to answer any ReadTheDocs bits, at least with regards to any account(s) or the like. There's no webhook associated with RTD from what I can tell, at the very least.

That said, I don't know if the issue is actually on their end. The build reports as passing from what I know to look at, but the lack of docs on RTD is due to a lack of conf files within the repo. The docs that get generated match what is in docs/, we just don't have much there. If we took a pass and either consolidated a config that doesn't need spoon-feeding for additional components/classes/etc, or at the very least dropped specific .rst conf files for the rest of the areas we care about docs for, that'd likely get us the majority of the way to "acceptable".

The last update 3 years ago was literally just a break-fix without making the larger effort of fully fleshing out our doc generation. I have the faint recollection of that being a purposeful "fix the immediate problem, throw doc generation on the backlog", but I don't remember specifics.

[bmr-cymru]

Hazarding a guess that @bmr-cymru is probably the best person to answer any ReadTheDocs bits, at least with regards to any account(s) or the like. There's no webhook associated with RTD from what I can tell, at the very least.

That was my first guess when I saw @arif-ali 's email - I checked though, and I am no longer the owner of sos on RTD - maintainers according to RTD are you & Stokes:

https://app.readthedocs.org/profiles/TurboTurtle/
https://app.readthedocs.org/profiles/battlemidget/

I seem to have given up all my privs there, so I can't even kick off a new build.

[TurboTurtle]

That's...surprising.

I just synced my github account to RTD, and there is now a webhook for the repo. I believe this should start rebuilds on merges to main now. I'll watch the next couple merges to see if that's actually working or if I need to do anything further there.

[TurboTurtle]

To recap here: the webhook has been re-added, and @arif-ali has made several changes to the in-repo config files. Additionally I've just enabled PR builds for docs, so we should start seeing results alongside our CI tests.

Anything else anyone wants to bring up here?