From 1f0da55f98c64ce8641d51510f0bfad7d7307ba7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Melissa=20Weber=20Mendon=C3=A7a?= Date: Fri, 2 Feb 2024 18:32:35 -0300 Subject: [PATCH] Exclude inherited tqdm members from documentation (#316) # 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. /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) --- docs/_templates/autosummary/class.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst index 9f33a7239..36c17e81d 100644 --- a/docs/_templates/autosummary/class.rst +++ b/docs/_templates/autosummary/class.rst @@ -5,7 +5,9 @@ .. autoclass:: {{ objname }} :members: :show-inheritance: - :inherited-members: + {% if objname != "progress" %} + :inherited-members: + {% endif %} {% block methods %}