ni / ni/nimi-python

Silent errors / warnings occur when building docs

Open
#1,913 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

docs priority-low
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.

  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.

  1. 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()

  1. 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.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.