Silent errors / warnings occur when building docs

[ni-jfitzger]

Description of issue

When building the docs, there are errors and warnings that only show up if passing the verbose (-v) argument to sphinxbuild.

1. viewcode import errors We get errors like

ModuleNotFoundError: No module named 'niscope.Session' viewcode can't import niscope.Session, failed with error "No module named 'niscope.Session'"

This is because we are incorrectly setting .. py:currentmodule:: ${module_name}.Session in class.rst. Session is a class, not a module. It should be .. py:currentmodule:: ${module_name}.session.

In nitclk, we are sometimes incorrectly setting .. py:currentmodule:: ${module_name}. This needs .session appended to it. Other times, we are setting .. py:currentmodule:: ${module_name}.SessionReference, which needs SessionReference to become session.

After fixing this, other problems are revealed.

2. Methods aren't being found

reading sources... [100%] niscope/class Didn't find abort in niscope.session Didn't find acquisition_status in niscope.session Didn't find add_waveform_processing in niscope.session ...

This can be fixed by specifying the class to which the method belongs. Example:

.. py:method:: abort() becomes .. py:method:: Session.abort()

3. Attributes aren't being found

Didn't find absolute_sample_clock_offset in niscope.session Didn't find acquisition_start_time in niscope.session Didn't find acquisition_type in niscope.session ...

I could not determine how to fix this.

Steps to reproduce issue

1. In tox.ini, change docs: sphinx-build -b html -d {envtmpdir}/doctrees . ../generated/docs/html {posargs} to docs: sphinx-build -v -b html -d {envtmpdir}/doctrees . ../generated/docs/html {posargs}
2. Run tox -e clean
3. Run tox -e codegen
4. Run tox -e docs

You will see the issues mentioned above.

[ni-jfitzger]

Fixing the viewcode issues would add source links to the documentation, at least for most methods. For some reason, it seems like others don't get the links.

I'm not sure there's much value in linking to the source, since our high level functions mostly just call the C API. We might be better off just disabling the viewcode extension.

We should perhaps fix the module, method references, anyway, but it may change the generated docs in ways we don't like. We would need to check changes in generated documentation carefully.