readthedocs docs not building

[newville]

The automated build of the docs at readthedocs.org is failing, for example https://readthedocs.org/api/v2/build/24927988.txt
The readthedocs version of the docs is stuck on version 3.2.1.

That build log suggests that it is fetching uncertainties from GitHub and installing stuff in doc/requirements.txt, but maybe not actually installing it with pip install, and then complaining that the file uncertainties/version.py does not exist. Well, that file is not in the repository and is generated at pip install time. Hm...

[jagerber48]

Ah just saw this issue. #257 will help with the version.py issue. Not sure how far that will readthedocs builds going.

It should be possible if we modify settings on readthedocs to get PRs to build docs as well so we can "dry run" docs building before merging into master. But for that we need maintainer privileges on readthedocs. I wonder if we can get those from @lebigot .

If I go to my readthedocs account, and then into my package I can click an "Admin" button and then there is a tab for "Maintainers" where maintainers can be added by username or e-mail address. jagerber48 is the username that should work for me.

[newville]

@jagerber48

#257 will help with the version.py issue.

I don't think #257 solves the issue, I think it just moves it. Building the sphinx documentation requires getting the version of uncertainties. In pyproject.toml this is configured to be set by setuptools and "setup" time (just prior to "install").

But whether the version string is found from the file uncertainties/version.py (or importing __version__ into __init__.py) or found from reading the PKG_INFO -- these have to be created at install time from the git tag as pyproject.toml instructs.

The real cause of issue is that the readthedocs config appears to not be installing uncertainties. It installs the dependencies, and then appears to expect to be able to run from the source tree without doing pip install. This is what no longer works (when moving to use setuptools_scm to set the version), and why #255 updates the readthedocs config to install uncertainties.

I don't fully understand the readthedocs config. I also don't love it. I use GitHub Pages for all of my other (at least 6?) projects. It requires no separate config or administration. It is true that docs have to be built somewhere and then uploaded and committed. I find that step of intentionally installing docs for each release to be better. I do not want public docs uploaded and available for every development version, unless I want to see them.

[jagerber48]

I dealt with each of these issues in sciform getting everything to work with readthe docs.

yes, conf.py needs the version. For that we do importlib.metadata.version("uncertainties") in conf.py. Pushing a commit with that change now.

As for the installation issue, I dealt with that one also. I think I solved it by adding . in the requirements.txt file that readthedocs reads. That way the build run pip install . at the start of the build which installs the locally available commit of readthedocs. I forget if readthedocs recently implemented a better requirements resolution strategy than a requirements.txt..

Sure, we can avoid public upload of dev docs. Let me see how this looks on sciform. It might be that you can configure which versions show up public but more versions can show up private. This may be an admin options.

I don't have a strong opinion that we stick with readthedocs over github pages or something else. readthedocs is just the only one I know.

[jagerber48]

It is true that docs have to be built somewhere and then uploaded and committed. I find that step of intentionally installing docs for each release to be better.

Sorry, are you describing a step in the github pages workflow or the readthedocs workflow? Or both? I'd like to see the docs built by readthedocs on #257 but don't know how to do that without admin privileges.

[jagerber48]

Yeah, I think my workflow here would be, if I were an admin in readthedocs, to explicitly allow a branch like more_readthedocs_config to build so that we can see that it works for #255. But this is a rare type of PR that is changing the readthedocs config. For more typical changes like regular updates to the docs I think those can be checked with local builds of the documentation and then merged to master. Unless you have a better workflow for previewing doc changes online before merging.

[jagerber48]

The docs are still not building