Guide for building documentation

[Harry-Lees]

I have been having some trouble building the docs locally on my machine. When I install all of the project dependencies and run make doc I get the following errors:

(aiodocker) 9:04:12 harrylees@Harrys-MBP.localdomain aiodocker main ? make doc
Running Sphinx v8.1.3
WARNING: Invalid configuration value found: 'language = None'. Update your configuration to a valid language code. Falling back to 'en' (English).
loading translations [en]... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
ERROR: Invalid value `None` in intersphinx_mapping['https://docs.python.org/']. Expected a two-element tuple or list.

Configuration error:
Invalid `intersphinx_mapping` configuration (1 error).
make[1]: *** [html] Error 2
make: *** [doc] Error 2

I assume this is due to a Sphinx version error, I have tried to fix some of the Sphinx errors with the following changes

diff --git a/docs/conf.py b/docs/conf.py
index 4db44f9..530422b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -102,7 +102,7 @@ release = "{major}.{minor}.{patch}-{tag}".format(**_version_info)
 #
 # 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"

 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -243,6 +243,6 @@ texinfo_documents = [
 # Example configuration for intersphinx: refer to the Python standard
 # library.
 intersphinx_mapping = {
-    "https://docs.python.org/": None,
+    "https://docs.python.org/": ("https://docs.python.org/", None),
     "aiohttp": ("https://aiohttp.readthedocs.io/en/stable/", None),
 }

But I still end up with the following error:

(aiodocker) 9:04:15 harrylees@Harrys-MBP.localdomain aiodocker main ? make doc
Running Sphinx v8.1.3
loading translations [en]... done
Converting `source_suffix = '.rst'` to `source_suffix = {'.rst': 'restructuredtext'}`.
loading intersphinx inventory 'https://docs.python.org/' from https://docs.python.org/objects.inv ...
loading intersphinx inventory 'aiohttp' from https://aiohttp.readthedocs.io/en/stable/objects.inv ...
intersphinx inventory has moved: https://docs.python.org/objects.inv -> https://docs.python.org/3/objects.inv
intersphinx inventory has moved: https://aiohttp.readthedocs.io/en/stable/objects.inv -> https://docs.aiohttp.org/en/stable/objects.inv
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 16 source files that are out of date
updating environment: [new config] 16 added, 0 changed, 0 removed
reading sources... [  6%] client
Exception occurred:
  File "/Users/harrylees/Documents/GitHub/aiodocker/.venv/lib/python3.10/site-packages/sphinx/domains/python/_object.py", line 267, in handle_signature
    raise TypeError(msg)
TypeError: Python directive method get_signature_prefix() must return a list of nodes. Return value was 'coroutine '.
The full traceback has been saved in /var/folders/00/mq7bsj5n4dxb29zztt408v280000gn/T/sphinx-err-ptm5fsmt.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make[1]: *** [html] Error 2
make: *** [doc] Error 2

Environment

(aiodocker) 9:02:39 harrylees@Harrys-MBP.localdomain aiodocker main ? python --version
Python 3.10.13

(aiodocker) 9:03:03 harrylees@Harrys-MBP.localdomain aiodocker main ? uv pip freeze
aiohappyeyeballs==2.6.1
aiohttp==3.11.11
aiosignal==1.3.2
alabaster==1.0.0
async-timeout==5.0.1
attrs==25.3.0
babel==2.17.0
cattrs==24.1.3
certifi==2025.1.31
cfgv==3.4.0
charset-normalizer==3.4.1
click==8.1.8
codecov==2.1.13
coverage==7.8.0
distlib==0.3.9
docutils==0.21.2
exceptiongroup==1.2.2
filelock==3.18.0
frozenlist==1.6.0
identify==2.6.10
idna==3.10
imagesize==1.4.1
iniconfig==2.1.0
jinja2==3.1.6
lsprotocol==2023.0.1
markupsafe==3.0.2
multidict==6.1.0
mypy==1.14.1
mypy-extensions==1.1.0
nodeenv==1.9.1
packaging==24.2
platformdirs==4.3.7
pluggy==1.5.0
pre-commit==4.2.0
propcache==0.3.1
pygls==1.3.1
pygments==2.19.1
pytest==8.3.4
pytest-asyncio==0.25.0
pytest-cov==6.0.0
pytest-sugar==1.0.0
pyyaml==6.0.2
requests==2.32.3
ruff==0.8.4
ruff-lsp==0.0.59
snowballstemmer==2.2.0
sphinx==8.1.3
sphinx-autodoc-typehints==2.5.0
sphinxcontrib-applehelp==2.0.0
sphinxcontrib-asyncio==0.3.0
sphinxcontrib-devhelp==2.0.0
sphinxcontrib-htmlhelp==2.1.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==2.0.0
sphinxcontrib-serializinghtml==2.0.0
termcolor==3.0.1
tomli==2.2.1
towncrier==24.8.0
typing-extensions==4.13.2
urllib3==2.4.0
virtualenv==20.30.0
yarl==1.18.3