Silent errors / warnings occur when building docs
Nobody has claimed this yet.
Assessment
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Newbie friendliness
- 35/100
- Issue type
- Bug
- Clarity
- Mostly clear
- Activity status
- Stale
- Tech stack
- python
- Domain
- build-system, documentation
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.
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.
- Dominant language
- Python
- Stars
- 128
- Forks
- 110
- Avg merge
- 5d 14h
- Merged PRs (30d)
- 10
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.
More from ni/nimi-python
-
docs nitclk priority-low
Difficulty 1/5 Under an hour Newbie friendliness 68/100
ni/nimi-python#1993 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
ni/nimi-python#2164 · 1 comment ·
-
bug docs
Difficulty 1/5 Under an hour Newbie friendliness 48/100
ni/nimi-python#2162 ·
-
codegen enhancement
Difficulty 4/5 3-5 days Newbie friendliness 42/100
ni/nimi-python#2148 · 2 comments ·
-
Difficulty 3/5 1-2 days Newbie friendliness 45/100
ni/nimi-python#2122 ·
Similar issues
-
triage/confirmed
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
agentscope-ai/agentscope#2775 ·
-
comp/desktop P3 type/bug
Difficulty 1/5 Under an hour Newbie friendliness 92/100
NousResearch/hermes-agent#118866 ·
-
bug
Difficulty 1/5 Under an hour Newbie friendliness 90/100
apache/cloudstack#14222 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
-
bug
Difficulty 2/5 1-3 hours Newbie friendliness 82/100