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

[NoahStapp]

No description provided.

[ShaneHarvey]

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

[NoahStapp]

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

[ShaneHarvey]

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.

[NoahStapp]

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.

[blink1073]

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?

[ShaneHarvey]

/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.

[blink1073]

LGTM!