versioned_docs.md

Versioned docs - PyMC3

We gonna try out and see how we can use ReadTheDocs to host PyMC3 docs in a versioned fashion.

I am trying out things on my fork. So, three major tasks for today -

1. Build docs locally (This will help me understand what is needed to build documentation)
2. Setup ReadTheDocs
3. Try out some versioning stuff and see how to setup ReadTheDocs for this versioning

Building docs locally

$ git checkout main
$ git fetch upstream
$ git merge upstream/main
$ git submodule update --recursive
$ cd docs
$ make -C source -f Makefile html

And of course, many errors popped out. So, lets tackle them one by one -

1. Deleted missing transforms from transforms.rst.
2. Removed TensorType mention from utilities.rst.
3. Deleted the 161 line (containing the code x.logp({'z': 2.5})) from developer_guide.rst. This helped resolve AttributeError: 'TensorVariable' object has no attribute 'logp'
4. Commented out line 3863 (containing the code ax.plot(x, np.exp(interpolated.logp(x).eval()),'C1',label='Interpolated pdf',alpha=0.8,lw=3)) from pymc3/distributions/continuous.py. This helped solve another AttributeError: 'TensorVariable' object has no attribute 'logp'
5. Commented out lines 3864 to 3867 from pymc3/distributions/continuous.py in Interpolated class docstring. This helped resolve AttributeError: 'TensorVariable' object has no attribute 'random'.

From now, no errors. There are only warnings.

Now. Let's tackle the most brutal exception

Exception occurred:
  File "/Users/sayam/miniconda3/envs/pymc_dev/lib/python3.7/site-packages/jupyter_sphinx/ast.py", line 429, in get_widgets
    return notebook.metadata.widgets[WIDGET_STATE_MIMETYPE]
KeyError: 'application/vnd.jupyter.widget-state+json'

I run this

$ git submodule update --remote --merge

to update pymc-examples submodule. I think the earlier submodule update command did not fetch me the latest pymc-examples repo and that's the reason of that brutal exception. Oriol has already fixed this exception in pymc-examples repo's main branch. Thanks Oriol :)

Then

$ cd docs/source
$ make clean
$ make html

The docs are built locally and there are about 311 warnings.

Setting up ReadTheDocs

Created a .readthedocs.yml file by following readthedocs configuration docs. This file looks like -

version: 2

sphinx:
    configuration: docs/source/conf.py

python:
   version: 3.7
   install:
   - requirements: requirements-dev.txt

submodules:
    include: all
    recursive: true

• Pushed changes to branch versioned_docs.
• Login to ReadTheDocs portal.
• Add the PyMC3 fork there.
• Switch branch to versioned_docs from master.
• And build succeeded. Here are our latest docs https://pymc3-fork.readthedocs.io/en/latest/.

Versioning in ReadTheDocs

Lets cut a fake release -

• Updated version to 4.0.1 in pymc3/__init__.py.
• Commit, created a tag and pushed to origin
• Went to builds section in RTD portal and hit activate on v4.0.1
• Here are the versioned docs https://pymc3-fork.readthedocs.io/en/v4.0.1/
• Simple and straightforward
• But I am wondering why the "latest" labelled build started again during the build of v4.0.1? I had pointed latest to versioned_docs branch and there has been no change to it. I just created a commit, tagged and pushed it on a separate branch.

The versioned docs are working. And here are the follow ups -

Questions to answer -

1. Should we use conda in .readthedocs.yml file to install requirements and stuff? cc @Alex
2. And does it make a difference which python version ReadTheDocs use to build the docs? Now, it is python 3.7
3. Do we want to build docs at every commit merged to PyMC3 repo's main branch?
4. For how many previous releases do we need to include documentation?
5. Should we delete gh-pages branch if we have decided on ReadTheDocs for deploying documentation?

TODOs -

1. Need to inspect git blame if transforms actually got deleted from pymc3/disrtibutions/transforms.py
2. Get the Interpolated class docstring fixed instead of commenting out code.
3. Document the right way of updating pymc-examples submodule locally. ReadTheDocs made things simple and I hope the submodules are integrated correctly in ReadTheDocs builds.
4. Help fix 311 warnings popped during make html command.
5. Figure out how domain name can be integrated with ReadTheDocs
6. And how to add Google Analytics keys there.
7. Prepare to roll out a PR.

to update pymc-examples submodule. I think the earlier submodule update command did not fetch me the latest pymc-examples repo and that's the reason of that brutal exception
Document the right way of updating pymc-examples submodule locally. ReadTheDocs made things simple and I hope the submodules are integrated correctly in ReadTheDocs builds.

Take a look at what https://github.com/pymc-devs/pymc3/blob/main/build_and_deploy_docs.sh and https://github.com/pymc-devs/pymc3/blob/main/fast_build_docs.sh are doing with the submodule. IIRC, they automatically updated the submodule when I used them.

But I am wondering why the "latest" labelled build started again during the build of v4.0.1? I had pointed latest to versioned_docs branch and there has been no change to it. I just created a commit, tagged and pushed it on a separate branch.
Do we want to build docs at every commit merged to PyMC3 repo's main branch?

I think latest should point to main and be built with every commit, stable should point to the latest release and be the default version of the docs shown if going to docs.pymc.io

For how many previous releases do we need to include documentation?

I would start with 3.11.3, 4.0 (once released or prereleased) and latest/main. Plus documentation previews for PRs! I have seen for example xarray has this working with rtd

And does it make a difference which python version ReadTheDocs use to build the docs? Now, it is python 3.7

Both sphinx, its dependencies and pymc are compatible with multiple python versions, so it should not matter which python version is used as long as we keep it updated enough to be compatible with pymc3 (i.e. python 3.6 is no longer supported)

Should we delete gh-pages branch if we have decided on ReadTheDocs for deploying documentation?

Yes, but I would wait until after having rtd all set up and pointing to docs.pymc.io.

Figure out how domain name can be integrated with ReadTheDocs

This might need some work on the domain side too, and I don't know who has access/permissions/knows how it works

Need to inspect git blame if transforms actually got deleted from pymc3/disrtibutions/transforms.py

Brandon and Ricardo should now what happened

Help fix 311 warnings popped during make html command.

As long as they are sphinx warnings that don't prevent building the docs (unlike the widget error) I think it would be cool to fix but very low priority. Other things that generate no warning need to be fixed first, like new distributions being missing from the API page.

And how to add Google Analytics keys there.

The theme we use now is already compatible with google analytics and configured: https://github.com/pymc-devs/pymc3/blob/main/docs/source/conf.py#L179. I have checked and it has already logged the visits to your fork readthedocs hosted version.

Great review. Thanks @oriol.
Its starting weekend and I will be able to make some progress on this.