readthedocs troubleshooting

This wiki describes some of the troubleshooting steps for pvlib documentation issues on readthedocs.

Go to the project’s build page: https://readthedocs.org/projects/pvlib-python/builds/

Click the “Build Version” button to start a new build. Builds often fail for random reasons beyond our control. This starts up a new build while you investigate the existing problem.

Click on the most recent failed build to investigate the problem.

If the problem occurs before the cat docs/sphinx/source/conf.py step, then the problem is in the build environment. It could be due to readthedocs or it could be due to something about the pvlib python dependencies in setup.py.

If the problem occurs after the cat step, then it’s more likely to be due to a bug in pvlib. Sometimes bad docstrings, particularly those with equations, can cause builds to fail. Sometimes exceptions that occur in IPython Directive calls cause builds to fail. Bad links typically only result in build warnings.

You can also try to wipe the cached build environment by going to https://readthedocs.org/projects/pvlib-python/versions/ and clicking edit next to the appropriate build (probably latest). This only forces readthedocs to rebuild the project build environment. It does not delete the active html pages.