Skip to content

PYTHON-3738 Use tox for sphinx doc instead of setup.py #1245

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
Jun 20, 2023
Merged

PYTHON-3738 Use tox for sphinx doc instead of setup.py #1245

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d49427f
PYTHON-3738 Use tox for sphinx doc instead of setup.py
NoahStapp Jun 15, 2023
852aaf2
Add linkcheck command to tox
NoahStapp Jun 16, 2023
132caf0
Update tox envs
NoahStapp Jun 16, 2023
0ed29fa
Fix tox doc env
NoahStapp Jun 16, 2023
a58ecc8
Fix linkcheck action dependency path
NoahStapp Jun 16, 2023
2362932
Fix typo
NoahStapp Jun 16, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 2 additions & 4 deletions .github/workflows/test-python.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,9 +83,7 @@ jobs:
cache-dependency-path: 'setup.py'
- name: Install dependencies
run: |
python -m pip install -U pip
python -m pip install sphinx
pip install tox
- name: Check links
run: |
cd doc
make linkcheck
tox -e linkcheck
35 changes: 34 additions & 1 deletion tox.ini
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,20 @@ envlist =
lint,
# Run pre-commit on all files, including stages that require manual fixes.
lint-manual,
# Typecheck using mypy.
typecheck-mypy,
# Typecheck using pyright.
typecheck-pyright,
# Typecheck using pyright strict.
typecheck-pyright-strict,
# Typecheck all files.
typecheck
typecheck,
# Build sphinx docs
doc,
# Test sphinx docs
doc-test,
# Linkcheck sphinx docs
linkcheck

[testenv:test]
description = run unit tests
Expand Down Expand Up @@ -75,3 +87,24 @@ commands =
{[testenv:typecheck-mypy]commands}
{[testenv:typecheck-pyright]commands}
{[testenv:typecheck-pyright-strict]commands}

[testenv:doc]
description = build sphinx docs
deps =
sphinx
commands =
sphinx-build -E -b html doc ./doc/_build/html
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should we add -W --keep-going -T?:

  -W                turn warnings into errors
  --keep-going      with -W, keep going when getting warnings
  -T                show full traceback on exception

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we currently use those options? I get a lot of warnings when running locally before using tox for building the docs.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We don't use them yet but looks like we have no warnings:

sphinx-build -E -b html doc ./doc/_build/html -W --keep-going -T
Running Sphinx v7.0.1
loading intersphinx inventory from https://www.gevent.org/objects.inv...
loading intersphinx inventory from https://docs.python.org/3/objects.inv...
building [mo]: targets for 0 po files that are out of date
writing output... 
building [html]: targets for 82 source files that are out of date
updating environment: [new config] 82 added, 0 changed, 0 removed
reading sources... [100%] tutorial                                                                                                                     
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] tutorial                                                                                                                      
generating indices... genindex py-modindex done
writing additional pages... search done
copying images... [100%] static/periodic-executor-refs.png                                                                                             
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build succeeded.

The HTML pages are in doc/_build/html.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I get 15 warnings running on my local machine:

/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst:3: ERROR: Error in "currentmodule" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. currentmodule:: {{ module }}
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/class.rst:3: ERROR: Error in "currentmodule" directive:
maximum 1 argument(s) allowed, 3 supplied.

.. currentmodule:: {{ module }}
WARNING: invalid signature for autoclass ('{{ objname }}')
WARNING: don't know which module to import for autodocumenting '{{ objname }}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: invalid signature for automodule ('{{ fullname }}')
WARNING: don't know which module to import for autodocumenting '{{ fullname }}' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst:53: ERROR: Unknown directive type "autosummary".

.. autosummary::
   :toctree:
   :recursive:
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst:56: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst:58: WARNING: Definition list ends without a blank line; unexpected unindent.
looking for now-outdated files... none found
pickling environment... done
checking consistency... /Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/Jinja2-3.1.2.dist-info/LICENSE.rst: WARNING: document isn't included in any toctree
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/MarkupSafe-2.1.3.dist-info/LICENSE.rst: WARNING: document isn't included in any toctree
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/imagesize-1.4.1.dist-info/LICENSE.rst: WARNING: document isn't included in any toctree
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst: WARNING: document isn't included in any toctree
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/class.rst: WARNING: document isn't included in any toctree
/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/module.rst: WARNING: document isn't included in any toctree
done
preparing documents... done
writing output... [100%] tutorial
generating indices... genindex py-modindex done
writing additional pages... search done
copying images... [100%] static/periodic-executor-refs.png
copying static files... done
copying extra files... done
dumping search index in English (code: en)... done
dumping object inventory... done
build finished with problems, 15 warnings.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I don't think we currently handle warnings from sphinx. @NoahStapp can you please open a new issue with that traceback to track handling warnings?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

/Users/nstapp/Github/mongo-python-driver/doc/lib/python3.11/site-packages/sphinx/ext/autosummary/templates/autosummary/base.rst:3: ERROR: Error in "currentmodule" directive:

Uh it looks like you have an errant virtualenv in your doc/ directory. doc/lib/python3.11 should not exist.


[testenv:doc-test]
description = run sphinx doc tests
deps =
{[testenv:doc]deps}
commands =
sphinx-build -E -b doctest doc ./doc/_build/doctest

[testenv:linkcheck]
description = check links of sphinx docs
deps =
{[testenv:doc]deps}
commands =
sphinx-build -E -b linkcheck doc ./doc/_build/linkcheck