pymc-devs/pymc

Clean up documentation build warnings

Open

#5,427 opened on Jan 30, 2022

View on GitHub
 (1 comment) (0 reactions) (0 assignees)Python (7,926 stars) (1,902 forks)batch import
docshelp wanted

Description

Description of your problem

When building docs there is a cascade of warnings, from reference issues to unused files. It would be great to clean these up as the preexisting warnings make it challenging to add docs, as new warnings are lost in a sea of red.

Namely there are some general categories of what needs to be done

Fix formatting issues that are raising warnings

/home/canyon/repos/pymc/docs/source/api.rst:38: WARNING: Bullet list ends without a blank line; unexpected unindent. /home/canyon/repos/pymc/docs/source/api.rst:41: WARNING: Bullet list ends without a blank line; unexpected unindent.

Clear autodoc import issues

WARNING: autodoc: failed to import method 'Chain.init' from module 'transforms'; the following exception was raised: No module named 'transforms' WARNING: autodoc: failed to import method 'Chain.backward' from module 'transforms'; the following exception was raised: No module named 'transforms' WARNING: autodoc: failed to import method 'Chain.forward' from module 'transforms'; the following exception was raised: No module named 'transforms'

Determine what to do with unlinked documents /home/canyon/repos/pymc/docs/source/api/math.rst: WARNING: document isn't included in any toctree /home/canyon/repos/pymc/docs/source/api/shape_utils.rst: WARNING: document isn't included in any toctree

There may be others as well

image

Dependencies

jupyter-sphinx==0.3.2
pydata-sphinx-theme==0.7.2
sphinx-copybutton==0.4.0
sphinx-design==0.0.13
sphinx-notfound-page==0.8
sphinx-remove-toctrees==0.0.3
sphinx-togglebutton==0.2.3
sphinxcontrib-applehelp==1.0.2
sphinxcontrib-devhelp==1.0.2
sphinxcontrib-htmlhelp==2.0.0
sphinxcontrib-jsmath==1.0.1
sphinxcontrib-qthelp==1.0.3
sphinxcontrib-serializinghtml==1.1.5

Contributor guide

Tech stack
python
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-2 days
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
stale
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
mostly clear
Prerequisites
PythonSphinx documentationreStructuredText syntax
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
60
Research direction
Focus on fixing the formatting warnings in docs/source/api.rst (lines 38, 41) by adding blank lines. Investigate the autodoc import issues for module 'transforms' – the module may be missing or misnamed; check if it should be imported from somewhere else or if the docstring references are incorrect. For unlinked documents (api/math.rst, api/shape utils.rst), decide whether to include them in a toctree or mark them as orphan. Review the Sphinx configuration and dependencies listed to replicate the build and verify fixes.