docs: move docs from juju.is

[tmihoc]

As part of a broader move where juju.is docs go federated and RTD, this PR adds all the python-libjuju material we previously had under juju.is/docs/juju (in how-to guide tabs) to the python-libjuju RTD (under a new section called "How-to guides").

This RTD project could use a lot of further improvements (e.g., for all of the other projects -- juju, terraform-provider-juju, charmcraft, ops -- I made sure to update the homepage according to the standard template and to have the full Diataxis tree and integrate the new content nicely with the old, removing duplication, etc.). However, given that we are slowly phasing python-libjuju out, I believe leaving things as is is probably fine.

There is one fix that it is worth making, namely, the links to Juju docs. I followed the instructions in https://canonical-documentation-with-sphinx-and-readthedocscom.readthedocs-hosted.com/style-guide/#internal-references for "targets in other doc sets", but the links don't seem to be working. It could be because the Juju RTD project needs some fixing (we're working on it). I should know soon enough what needs to be done and then I'll come back and fix all the links in a follow-up PR.

QA Steps

From the root of the repo:

# Build the docs:
tox -e docs 

#Preview the docs:
open docs/_build/index.html

[benhoyt]

Thanks for this, @tmihoc! However, it looks like you've accidentally commits all the Python files under build/*. Where are these files coming from? Should the /build directory be added to .gitignore?

[james-garner-canonical]

I've taken care of rebasing this branch, and added a commit that removes build/ and #manage-machines.rst#, updates .gitignore to ignore build/, and adds the (mostly whitespace) changes mandated by pre-commit.

[tonyandrewmeyer]

This makes sense to me. The how-to guides are integrated, which is the main point, and while the docs site is still not great, I agree that it doesn't make sense to fix that given where things are headed.

For the broken Juju docs, the plan to fix them in a future PR seems fine - I don't think it needs to block merging, even though we did that that approach with ops. For what it's worth, I don't see the juju cross-Sphinx link defined, so that may be the problem?

[dimaqq]

first read

[tmihoc]

@james-garner-canonical I see you've already committed some improvements. Do you think I could leave this PR in your hands? Asking because I'm juggling changes in a few other repos at the moment and I could use all the help I can get.

[james-garner-canonical]

I've merged @dimaqq's suggestions and signed the commit.

Re: linking to Juju docs, @tonyandrewmeyer's comment pointed me to us needing to define the juju: reference for sphinx. intersphinx is already in docs/conf.py's extensions, so I guess we need something like this -- but what url do we use here? http://canonical-juju.readthedocs-hosted.com/

intersphinx_mapping = {
    'python': ('https://docs.python.org/3', None),
    "juju": (JUJU_DOCS_URL, None),
}

[james-garner-canonical]

I guess if we go with @tmihoc's original suggestion to fix the Juju links in a subsequent PR, then this might be ready to merge. Any objections, @benhoyt and @dimaqq ?

[benhoyt]

Yep, I'm good with it.

The only minor thing I noticed when viewing locally is the breadcrumbs at the top of the page have a "" in them:

[james-garner-canonical]

/merge