I have a small project at github. The package does not have external dependencies, and all the source is included in a single __init__.py file. In the ./docs folder, I just have 2 rst files: an index.rst with some intro and a nix_shell_utils.rst file where the package members are automatically described from their docstrings:
nix_shell_utils.rst file
nix_shell_utils package
=========================
.. automodule:: nix_shell_utils
:members:
:undoc-members:
:show-inheritance:
The ./docs/conf.py is quite standard:
# Configuration file for the Sphinx documentation builder.
#
# For the full list of built-in configuration values, see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
# -- Project information -----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
project = 'nix_shell_utils'
copyright = '2022, Alberto Garcia Izquierdo'
author = 'Alberto Garcia Izquierdo'
release = '0.0.1'
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
extensions = [
'sphinx.ext.autodoc',
'sphinx.ext.viewcode',
'sphinx.ext.autosummary',
'sphinx.ext.napoleon'
]
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
html_theme = 'sphinx_rtd_theme'
#html_static_path = ['_static']
# -- Options for autodoc ----------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#configuration
# Automatically extract typehints when specified and place them in
# descriptions of the relevant function/method.
autodoc_typehints = "description"
# Don't show class signature with the class' name.
autodoc_class_signature = "separated"
autodoc_member_order = 'bysource'
when generating documentation locally with make html the process goes OK: when clicking on the nix_shell_utils link in the index.html page, I get to the nix_shell_utils.html page, where all the members of the package are rendered correctly by :automodule: from their docstrings:
However, when I tried to do the same in readthedocs.org, the build process terminates OK, but when clicking on the nix_shell_utils link at the documentation index, I just get a page with the title, "Module Contents" header, and nothing else. Readthedocs does not render the documentation of the package members from their docstrings.
My .readthedocs.yaml is pretty standard
version: 2
build:
os: "ubuntu-22.04"
tools:
python: "3.10"
python:
install:
- method: pip
path: .
And the log from the readthedocs building process does not indicate any problem:
Running Sphinx v5.3.0
making output directory... done
[autosummary] generating autosummary for: index.rst, nix_shell_utils.rst
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [ 50%] index
reading sources... [100%] nix_shell_utils
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [ 50%] index
writing output... [100%] nix_shell_utils
generating indices... genindex py-modindex done
highlighting module code... [100%] nix_shell_utils
writing additional pages... search done
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
Updating searchtools for Read the Docs search... build succeeded.
The HTML pages are in _build/html.
I have looked at similar questions in stackoverflow, but for most of them either the package to be documented has not been installed prior to run the doc build (not my case), or they have external dependencies that have not been installed (I don't have any). I've tried to set up exactly the same environment locally and in readthedocs (ubuntu 22.04, Python 3.10, Sphinx v5.30) and also run the same command as in readthedocs locally
python -m sphinx -T -E -b html -d _build/doctrees -D language=en . _build/html
But again, locally autodoc members are rendered correctly, while on readthedocs they don't.
Any idea of why this is happening?
However, when I tried to do the same in readthedocs.org, the build process terminates OK, but when clicking on the nix_shell_utils link at the documentation index, I just get a page with the title, "Module Contents" header, and nothing else. Readthedocs does not render the documentation of the package members from their docstrings.
Maybe it was a cache issue? I do see the documentation properly at https://nix-shell-utils.readthedocs.io/en/latest/nix_shell_utils.html
It shows the docs for nix_shell_utils.mkdir, nix_shell_utils.cp and many other functions.