Merge pull request #871 from cderici/revisit-autodocs-sphinx

#871

#### Description

This is the first step to revive the auto doc generation (that hasn't been touched for more than 4 years now), so we can get that rolling whenever we land a PR or make a release the docs will be generated and [published on ReadTheDocs](https://pythonlibjuju.readthedocs.io/en/latest/). The infrastructure is working (i.e. RTD seems to be picking it up), we just need to fix the sphinx build there that's been failing for a long time https://readthedocs.org/projects/python-libjuju/builds/18115299/

I'm not entirely sure yet how to debug the build process on the RTD, however, this change updates and fixes the sphinx setup in the `docs`, so we can run `make html` and actually be able to render the docs. The rest is to be figured out.

#### QA Steps

```sh
$ cd docs
$ make html
$ <browser> _build/html/index.html
```

#### Notes & Discussion

- I'm not entirely sure but there might be some local package requirements, which I had to install but I can't remember, I think one of them was `python3-sphinxcontrib-asyncio`.
- One of the huge advantages of this is that it also generates a reference for the internal API coming from the facade schema, which allows us (the developers) to see the parameters without going into the depths of the `juju/client/`. For example, check out the `_definitions` module [here](https://pythonlibjuju.readthedocs.io/en/latest/api/juju.client.html#module-juju.client._definitions)

Author: jujubot

docs/Makefile

@@ -9,7 +9,7 @@ BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-	$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
+$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don\'t have Sphinx installed, grab it from http://sphinx-doc.org/)
 endif
 
 # Internal variables.

docs/_extensions/automembersummary.py

@@ -18,9 +18,9 @@
 import textwrap
 
 from docutils import nodes
+from docutils.parsers.rst import Directive
 from docutils.statemachine import ViewList
 from sphinx.errors import SphinxError
-from sphinx.util.compat import Directive
 from sphinx.util.nodes import nested_parse_with_titles
 
 

docs/api/juju.cloud.rst

@@ -11,7 +11,9 @@ endpoints for secrets backend.
 
 This release works with any Juju 3.x controller.
 
-## What's Changed
+What's Changed
+==============
+
 * [JUJU-3202] Add facades for 3.1.1. by @juanmanuel-tirado in https://github.com/juju/python-libjuju/pull/807
 * Add destroy units by @cderici in https://github.com/juju/python-libjuju/pull/812
 * [JUJU-3517] Revisit _build_facades in connection by @cderici in https://github.com/juju/python-libjuju/pull/826
@@ -29,7 +31,9 @@ Connectivity with juju controllers in the 3.x series is allowed, connections wit
 
 This version is only tested using Juju 3.1.0.
 
-## What's Changed
+What's Changed
+==============
+
 * setup.py: adjust websockets versions for py38-310 by @mert-kirpici in https://github.com/juju/python-libjuju/pull/731
 * [JUJU-2175] Remove juju 2.9 support on 3.1.0 by @juanmanuel-tirado in https://github.com/juju/python-libjuju/pull/774
 * [JUJU-2276] Series or base for local charms by @cderici in https://github.com/juju/python-libjuju/pull/777
@@ -42,7 +46,9 @@ This version is only tested using Juju 3.1.0.
 * Add compatibility for juju 3.1.0 by @juanmanuel-tirado in https://github.com/juju/python-libjuju/pull/799
 * Replace schemas.json with a wellformed version. by @juanmanuel-tirado in https://github.com/juju/python-libjuju/pull/800
 
-## New Contributors
+New Contributors
+================
+
 * @mert-kirpici made their first contribution in https://github.com/juju/python-libjuju/pull/731
 
 **Full Changelog**: https://github.com/juju/python-libjuju/compare/3.0.4...3.1.0.1
@@ -52,12 +58,16 @@ This version is only tested using Juju 3.1.0.
 
 Wednesday 26th October
 
-## What's Changed
+What's Changed
+==============
+
 * [JUJU-2027] Local refresh with resoruces by @cderici in https://github.com/juju/python-libjuju/pull/757
 * [JUJU-2026] Improve resolve charm by @cderici in https://github.com/juju/python-libjuju/pull/761
 * Add owner and data to license file by @arturo-seijas in https://github.com/juju/python-libjuju/pull/760
 
-## New Contributors
+New Contributors
+================
+
 * @arturo-seijas made their first contribution in https://github.com/juju/python-libjuju/pull/760
 
 **Full Changelog**: https://github.com/juju/python-libjuju/compare/3.0.3...3.0.4
@@ -67,7 +77,8 @@ Wednesday 26th October
 
 Saturay October 22 2022
 
-## What's Changed
+What's Changed
+==============
 
 * Wait for idle arg type check by @cderici in https://github.com/juju/python-libjuju/pull/741
 * [JUJU-1970] Revise local refresh by @cderici in https://github.com/juju/python-libjuju/pull/742
@@ -87,7 +98,8 @@ Saturay October 22 2022
 
 Wednesday October 5 2022
 
-## What's Changed
+What's Changed
+==============
 
 * Model name can now be accessed through model.name by @jack-w-shaw in https://github.com/juju/python-libjuju/pull/702
 * [JUJU-1593] Fix `unit.run()` and update the old client codes by @cderici in https://github.com/juju/python-libjuju/pull/710

docs/changelog.rst

@@ -77,7 +77,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -300,4 +300,4 @@
 #texinfo_no_detailmenu = False
 
 def setup(app):
-    app.add_stylesheet('custom.css')
+    app.add_css_file('custom.css')

docs/conf.py

@@ -1,5 +1,5 @@
-pytz<2018.0,>=2017.2  # conflict between sphinx and macaroonbakery
+pytz==2021.1
 pymacaroons>=0.13.0,<1.0  # force new version with pynacl instead of libnacl
-sphinx==1.6.5
+sphinx==4.3.2
 sphinxcontrib-asyncio
 sphinx_rtd_theme