You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
When building the docs, there are errors and warnings that only show up if passing the verbose (-v) argument to sphinxbuild.
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.
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:
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.
Description of issue
When building the docs, there are errors and warnings that only show up if passing the verbose (-v) argument to sphinxbuild.
We get errors like
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 needsSessionReference
to becomesession
.After fixing this, other problems are revealed.
This can be fixed by specifying the class to which the method belongs.
Example:
.. py:method:: abort()
becomes.. py:method:: Session.abort()
I could not determine how to fix this.
Steps to reproduce issue
docs: sphinx-build -b html -d {envtmpdir}/doctrees . ../generated/docs/html {posargs}
todocs: sphinx-build -v -b html -d {envtmpdir}/doctrees . ../generated/docs/html {posargs}
tox -e clean
tox -e codegen
tox -e docs
You will see the issues mentioned above.
The text was updated successfully, but these errors were encountered: