Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

API Reference not populated in online docs #1840

Closed
EliahKagan opened this issue Feb 23, 2024 · 1 comment · Fixed by #1843
Closed

API Reference not populated in online docs #1840

EliahKagan opened this issue Feb 23, 2024 · 1 comment · Fixed by #1843

Comments

@EliahKagan
Copy link
Contributor

EliahKagan commented Feb 23, 2024

In the Read the Docs deployment, the API Reference page is unpopulated: the sections exist, but they do not contain any entries from the classes, functions, etc., that are supposed to go there.

This only affects the online documentation. Building the documentation locally still works with make -C doc html, provided the necessary dependencies are installed, and the API Reference page is fully populated. (This is how I have usually verified tricky or substantial changes to the documentation, and I was able to do it with no problems to check #1839.)

Furthermore, it only affects documentation from after #1794 was fixed. For a while before it was fixed, no new documentation was deployed online. But the API Reference page worked before that, and still works when accessed on readthedocs.org for those old versions.

It seems the changes made in 634151a to fix #1794 were sufficient to get documentation to build again, but not sufficient to set up Read the Docs in such a way that it would be able to populate members for code like:

.. automodule:: git.cmd
:members:
:undoc-members:
:special-members:

I don't know why this is or how best to investigate it, and I am not experienced with Read the Docs. But a couple of possibilities occur to me, both based in part on my observation that, when I build the documentation locally, the generated documentation shows values for attributes that are populated from environment variables, where the value I set for the environment variable is the value shown in the documentation. In other words, building the documentation relies on being able to import the modules and makes use of state set from running their top-level code.

If Read the Docs is itself (re)building the documentation--which if I understand correctly is what the new .readthedocs.yaml configures--then perhaps it is unable to successfully import those modules:

  1. Does it have the necessary Python dependencies?
  2. Does the container that builds the documentation have a git command?

I reiterate that Read the Docs deployment is not an area where I am currently knowledgeable.

@Byron
Copy link
Member

Byron commented Feb 23, 2024

Thanks for bringing this to my attention, I wasn't aware.

I wanted to share some build logs that seem to be publicly accessible for further examination:

It keeps saying that it can't find the gitdb module, maybe this is what's preventing it from building the API docs? If so, is there a way to configure it to install necessary dependencies?

EliahKagan added a commit to EliahKagan/GitPython that referenced this issue Feb 23, 2024
This configures Read the Docs builds to be more like local builds
in two ways:

- Pass "-W", as is done in a local build with "make -C doc html",
  so that if there are broken references, the build fails.

- Install dependencies. This configures the Python environment, via
  the python.install key, so that RTD builds install requirements.

More specifically on dependency installation, it does two things:

1. The equivalent of "pip install .", which installs the project
   and its dependencies (though not any extras). This includes the
   gitdb dependency, which is needed to import GitPython's git
   module to populate sections in the API Reference page (gitpython-developers#1840).

2. The equivalent of "pip install -r doc/requirements.txt", which
   installs the additional Sphinx-related dependencies used when
   building documentation locally.

Installing Sphinx-related dependencies is useful for three reasons:

a. Least importantly, it should increase consistency between remote
   (RTD) and local documentation builds.

b. It may be needed to avoid warnings that are not being fixed at
   this time, while still allowing the build to succeed with the
   "-W" option (see above on that change) that causes failure for
   immediately addressable problems. The effect of newer versions
   of Sphinx carrying a few extra hard-to-fix warnings for
   GitPython is noted in gitpython-developers#1802 (and is why they are not upgraded
   in gitpython-developers#1803).

c. One of the documentation build dependencies listed in
   doc/requirements.txt is sphinx_rtd_theme. In 634151a (for gitpython-developers#1794)
   the line specifying this theme was commented out, since it
   apparently broke in the build. This may allow it to be used
   again (or can be replaced with another custom theme if desired).

This also reenables the sphinx_rtd_theme theme disabled in 634151a.

Finally, this makes minor changes to .readthedocs.yml's comments
and formatting so the comments are accurate for GitPython details
and so the file is formatted in the same style as other YAML here.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Development

Successfully merging a pull request may close this issue.

2 participants