aio-libs / aio-libs/aiodocker

Guide for building documentation

Abierto
#968 0 comentarios 0 reacciones 0 asignados Ver en GitHub
Lenguaje dominante
Python
Estrellas
537
Forks
118
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

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
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 . 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
```

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.