Skip to content

Commit

Permalink
Exclude inherited tqdm members from documentation (#316)
Browse files Browse the repository at this point in the history
# References and relevant issues
Addresses #111 - reduces current sphinx errors from 208 to 135

# Description
This change excludes inherited tqdm methods from being documented in the
API docs for `napari.utils.progress`.

Before this change, when building the docs we can see the following
error messages:

```sh
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:36: ERROR: Unexpected indentation.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:37: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:42: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:50: WARNING: Inline emphasis start-string without end-string.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.wrapattr:3: ERROR: Unexpected indentation.
<snip>
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:36: ERROR: Unexpected indentation.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:37: WARNING: Block quote ends without a blank line; unexpected unindent.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:42: WARNING: Definition list ends without a blank line; unexpected unindent.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.format_meter:50: WARNING: Inline emphasis start-string without end-string.
/home/melissa/micromamba/envs/napari-dev/lib/python3.11/site-packages/napari/utils/progress.py:docstring of tqdm.std.tqdm.wrapattr:3: ERROR: Unexpected indentation.
```

These errors also create formatting issues on the [rendered api
docs](https://napari.org/dev/api/napari.utils.progress.html?highlight=progress#napari.utils.progress).

The only drawback to this change is that only the new napari methods are
documented, but my thinking is since we already link to the tqdm
documentation from the progress docstring, users can find any extra
information there. Here is how the details rubric in the progress
documentation looks like after the change:

![Screenshot_20240109_131118](https://github.com/napari/docs/assets/3949932/ca30820a-0c26-4c3c-8673-a1d706d68a91)
  • Loading branch information
melissawm authored Feb 2, 2024
1 parent 46ba5ba commit 1f0da55
Showing 1 changed file with 3 additions and 1 deletion.
4 changes: 3 additions & 1 deletion docs/_templates/autosummary/class.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,9 @@
.. autoclass:: {{ objname }}
:members:
:show-inheritance:
:inherited-members:
{% if objname != "progress" %}
:inherited-members:
{% endif %}

{% block methods %}

Expand Down

0 comments on commit 1f0da55

Please sign in to comment.