Moonray docs

[evilnick]

• adds moonray sphinx instance for generating docs
• adds substitution terms
• converts existing docs to use substitution
• fixes a few CAPI docs

Currently the Moonray docs are available here - https://canonical-moonray.readthedocs-hosted.com/docs-moonray-staging/
N.B. there is minimal content there yet

NB this replaces #578

[evilnick]

Also adds a workflow to integrate standard doc test - I have left this as run on demand at the moment because it is going to spew out millions of errors

[evilnick]

You can check no Canonical kubernetes was hurt during this operation by viewing these docs
The new, largely empty Moonray stuff is here

[louiseschmidtgen]

This is looking great, please add some TODOs or add missing files so that we don't accidentally forget about broken links.
Please check the the mirrored pages like ../../src/snap/howto/install/snap.md and their links.

[evilnick]

thanks @louiseschmidtgen. I added a TODO on one file and just removed a lot of references elsewhere to resolve the broken links

Some of how this is going to work moving forward is going to require some careful editing of the 'common' pages and probably some changes to the structure so that things just work, but thats for another PR

[bschimke95]

great work @evilnick

An initial question:

What is the reason for the moonray docs to be in docs/moonray and duplicate the setup like this? Looking at the code, it seems a bit odd to have docs/src/... and docs/moonray. I'd either move moonray to the src folder or rename src to something that reflects that these are the default docs (e.g. core?).

[evilnick]

Thanks @bschimke95. So, the eventual intention is something like this:

├── canonicalk8s
│   ├── index
│   └── sphinx
├── moonray
│   ├── index
│   └── sphinx
└── src
    ├── capi
    │   ├── explanation
    │   ├── howto
    │   │   ├── getting_started.md
    │   │   ├── getting_started_mr.md
    │   │   └── index
    │   ├── reference
    │   └── tutorials
    ├── _parts
    └── snap
        ├── explanation
        ├── howto
        │   ├── getting_started.md
        │   ├── getting_started_mr.md
        │   └── index
        ├── reference
        └── tutorials

and possibly rename src to something better like 'content' maybe? That will also require changing the readthedocs config here, and the build scripts on the RTD site and will have to be done in stages

As they are published on different sites, the moonray and canonical k8s need their own sphinx setups - their own config etc. They also require their own top-level index to control the content. They can and should, as much as possible, use the same source files though. We can mostly achieve this using some features such as:

• including files or parts of files
• just using naming rules to differentiate things (e.g. a 'moonray' suffix or whatever)
• using conditional text (basically, if "moonray" then... blocks in the files (would like to avoid this as much as possible)

It would be possible to achieve this in one PR, but it is going to take considerably more time. At the moment the scope of this work is to enable us to publish moonray specific docs, which it does. The rest of the rebuilding-the-aircraft-in-flight will be tackled in future PRs, but this gets us where we need to be to publish things like CIS compliance and EPA stuff for moonray right now.

P.S. I appreciate the questioning though. Neither ReadTheDocs nor Sphinx have any defined way to create two distinct sets of documentation from the same source (Sphinx has some useful things here, but their concepts are based on different versions of the same docs) so this is very much trying to create a logical and sustainable (and extendable, if we ever have to make a 'starfall' or 'cometstrike' or whatever) process with the bits we have.

[bschimke95]

Thanks for the context @evilnick
The envisioned structure makes a lot of sense and also splitting up that work into multiple PRs is very reasonable.

[bschimke95]

LGTM