Split instructions for enabling doc builds and working with docs

[pmatulis]

Currently we have one readme.rst file that describes a mix of instructions:

• enabling/configuring RTD
• working with RTD once the above is done

In my experience of setting up RTD I've found that this mixture of instructions creates a bit of a mess once a repository is enabled. I'm advocating for two different files, one for each set of procedures. I'm fixing up an enabled repository right now and so I have stuff to contribute if people agree to the general idea.

[syncronize-issues-to-jira]

Thank you for reporting us your feedback!

The internal ticket has been created: https://warthogs.atlassian.net/browse/DOCPR-105.

This message was autogenerated

[ru-fu]

Hmm, what instructions do you feel shouldn't be in here?
I can't really see anything relating to RTD (except the note that you might need to configure the path to .readthedocs.yaml, depending on your setup). The instructions for working with RTD are here: https://library.canonical.com/documentation/publish-on-read-the-docs

Or do you mean just generally working with the documentation (building and viewing it)?

[pmatulis]

Or do you mean just generally working with the documentation (building and viewing it)?

Mostly that, but there is also the occasional need for modifying the .wordlist.txt file and the linkcheck_ignore variable.

[ru-fu]

OK, but none of this is related to Read the Docs. You can do all your doc building locally and host the output on another server if you want.

So you want to split out the instructions for setting up your Sphinx documentation and the ones for working with it? Since the RTD instructions are already split out into the Library.

[pmatulis]

Right, the use of the term "RTD" wasn't accurate. Apologies.

[ru-fu]

No problem, just got a bit confused. ;)

I'm fine with splitting it up. The only disadvantage I see is that only the README file is displayed automatically on the start page of the repo, so users will need to actively go to the other file. But that shouldn't be a big deal.

[ru-fu]

This is fixed through #165, right @pmatulis ?

[pmatulis]

@ru-fu Yep yep. Closing.