Silent errors / warnings occur when building docs

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

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

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

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

Dominant language
Python
Stars
128
Forks
110
Avg merge
5d 14h
Merged PRs (30d)
10

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.

More from ni/nimi-python

All issues in ni/nimi-python

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.