Silent errors / warnings occur when building docs
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 128
- Forks
- 110
- Avg merge
- 5d 14h
- Merged PRs (30d)
- 10
Description
Description of issue
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:
.. py:method:: abort() becomes .. py:method:: Session.abort()
- 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
- In tox.ini, change
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} - Run
tox -e clean - Run
tox -e codegen - Run
tox -e docs
You will see the issues mentioned above.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the verbose docs-build commands in tox.ini, then inspect the generated class.rst files and the nitclk directives that set py:currentmodule. Correct the module and method references described in the issue, and investigate the unresolved attribute warnings. Run tox -e clean, tox -e codegen, and tox -e docs; done means the documented viewcode, method, and attribute warnings are addressed.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation
- Issue type
- Bug
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100