Manual: CCB Documentation empty

[drewrisinger]

Question

Category: Documentation

Description

The Documentation on CCB/AppletsCCBDock is missing in the ARTIQ3-5 manuals online. See v5 and v4/v3

In v4:

artiq.dashboard.applets_ccb.AppletsCCBDock
    alias of <Mock id='140337887288456'>

No alias shows in v5

Must be some sort of Sphinx build issue?

[sbourdeauducq]

The alias isn't the correct thing to show either. Looks like a problem with the sphinx mock modules.

[HarryMakes]

This issue seems to have re-appeared. Someone seems to have fixed this bug on Sphinx (sphinx-doc/sphinx#8607) recently, so maybe we can override python3Packages.sphinx on Gitea's M-Labs/nix-scripts with version 3.4.2+ later on.

[sbourdeauducq]

We can use overrideAttrs(... patches = [(fetchurl https://patch-diff.githubusercontent.com/raw/sphinx-doc/sphinx/pull/8607.diff)]) (with the Nix syntax fixed, see it-infra where this is used in several places) - no need to wait for a release.

[HarryMakes]

I'm going to propose a fix on nix-scripts by:

• First, overriding the sphinx source entirely by bumping the version from "3.0.3" (nixpkgs 20.09) or "2.3.1" (nixpkgs 20.03) to "3.4.1". This seems to be necessary because the pull request I mentioned was forked from that version. Also note that the sphinx package is built with fetchPypi rather than fetchgit, and testing has shown that the source files involved are slightly different between the two (e.g. simply patching the diff of 3.0.3->the pull request commit would fail for certain files).
• Then, overriding the patches by adding the diff pulled from GitHub API to the list.

With initial testing (using nix-build -A artiq-manual-html artiq-full.nix), the build is successful. However, I did not get the expected doc contents for artiq.dashboard.applets_ccb.AppletsCCBDock. Instead, I got the following, which is similar to what I saw in v4:

So, I guess further investigation would still be needed, such as whether or not the conf.py needs to be edited.

[HarryMakes]

Proposing fix as in #1577. In newer versions of Sphinx, mocking artiq.dashboard (using unittest) would treat it as an alias of unittest.mock, which also seems to defeat the purpose of documenting the module such as the CCB class.

This fix has been tested locally using both the unpatched Sphinx version (i.e. v3.0.3) and patched version (e.g. sphinx-doc/sphinx@aaee352), so I'm quite confident about my fix this time.

[HarryMakes]

While we currently don't need to use newer version of Sphinx or apply any patches to it, it is worth noting that in case the package gets updated, we might need to apply autodoc_member_order = "bysource" in conf.py. In v3.0.3 Sphinx uses the source code order for listing the classes by default, but this (I believe) was a bug because Sphinx is supposed to use alphabetical order by default. So if we don't specify autodoc_member_order, all classes will be forced-listed in increasing alphabetical order using newer Sphinx (e.g. v3.4.1 or up).