Skip to content

Commit f9bfd11

Browse files
ShaneHarveyShaneHarvey
authored
PYTHON-2870 Add support for man/text/latex/etc.. docs output (#708)
Regenerate sphinx makefile with sphinx-quickstart 3.5.4. Remove problematic mongodoc sphinx extension.
1 parent 69c69a6 commit f9bfd11

18 files changed

+77
-323
lines changed

‎bson/dbref.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -42,7 +42,7 @@ def __init__(self, collection, id, database=None, _extra={}, **kwargs):
4242
- `**kwargs` (optional): additional keyword arguments will
4343
create additional, custom fields
4444
45-
.. mongodoc:: dbrefs
45+
.. seealso:: The MongoDB documentation on `dbrefs <https://dochub.mongodb.org/core/dbrefs>`_.
4646
"""
4747
if not isinstance(collection, str):
4848
raise TypeError("collection must be an instance of str")

‎bson/objectid.py

+1-1
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,7 @@ def __init__(self, oid=None):
8989
:Parameters:
9090
- `oid` (optional): a valid ObjectId.
9191
92-
.. mongodoc:: objectids
92+
.. seealso:: The MongoDB documentation on `ObjectIds`_.
9393
9494
.. versionchanged:: 3.8
9595
:class:`~bson.objectid.ObjectId` now implements the `ObjectID

‎doc/Makefile

+13-82
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,20 @@
1-
# Makefile for Sphinx documentation
1+
# Minimal makefile for Sphinx documentation
22
#
33

4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = sphinx-build
7-
PAPER =
4+
# You can set these variables from the command line, and also
5+
# from the environment for the first two.
6+
SPHINXOPTS ?=
7+
SPHINXBUILD ?= sphinx-build
8+
SOURCEDIR = .
89
BUILDDIR = _build
910

10-
# Internal variables.
11-
PAPEROPT_a4 = -D latex_paper_size=a4
12-
PAPEROPT_letter = -D latex_paper_size=letter
13-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14-
15-
.PHONY: help clean html dirhtml pickle json htmlhelp qthelp latex changes linkcheck doctest
16-
11+
# Put it first so that "make" without argument is like "make help".
1712
help:
18-
@echo "Please use \`make <target>' where <target> is one of"
19-
@echo " html to make standalone HTML files"
20-
@echo " dirhtml to make HTML files named index.html in directories"
21-
@echo " pickle to make pickle files"
22-
@echo " json to make JSON files"
23-
@echo " htmlhelp to make HTML files and a HTML help project"
24-
@echo " qthelp to make HTML files and a qthelp project"
25-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
26-
@echo " changes to make an overview of all changed/added/deprecated items"
27-
@echo " linkcheck to check all external links for integrity"
28-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
29-
30-
clean:
31-
-rm -rf $(BUILDDIR)/*
32-
33-
html:
34-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
35-
@echo
36-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
37-
38-
dirhtml:
39-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
40-
@echo
41-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
42-
43-
pickle:
44-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
45-
@echo
46-
@echo "Build finished; now you can process the pickle files."
47-
48-
json:
49-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
50-
@echo
51-
@echo "Build finished; now you can process the JSON files."
52-
53-
htmlhelp:
54-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
55-
@echo
56-
@echo "Build finished; now you can run HTML Help Workshop with the" \
57-
".hhp project file in $(BUILDDIR)/htmlhelp."
58-
59-
qthelp:
60-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
61-
@echo
62-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
63-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
64-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/PyMongo.qhcp"
65-
@echo "To view the help file:"
66-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/PyMongo.qhc"
67-
68-
latex:
69-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
70-
@echo
71-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
72-
@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
73-
"run these through (pdf)latex."
74-
75-
changes:
76-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
77-
@echo
78-
@echo "The overview file is in $(BUILDDIR)/changes."
13+
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
7914

80-
linkcheck:
81-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
82-
@echo
83-
@echo "Link check complete; look for any errors in the above output " \
84-
"or in $(BUILDDIR)/linkcheck/output.txt."
15+
.PHONY: help Makefile
8516

86-
doctest:
87-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
88-
@echo "Testing of doctests in the sources finished, look at the " \
89-
"results in $(BUILDDIR)/doctest/output.txt."
17+
# Catch-all target: route all unknown targets to Sphinx using the new
18+
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
19+
%: Makefile
20+
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

‎doc/conf.py

+1-2
Original file line numberDiff line numberDiff line change
@@ -14,8 +14,7 @@
1414
# Add any Sphinx extension module names here, as strings. They can be extensions
1515
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
1616
extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest', 'sphinx.ext.coverage',
17-
'sphinx.ext.todo', 'doc.mongo_extensions',
18-
'sphinx.ext.intersphinx']
17+
'sphinx.ext.todo', 'sphinx.ext.intersphinx']
1918

2019
# Add any paths that contain templates here, relative to this directory.
2120
templates_path = ['_templates']

‎doc/examples/encryption.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ level encryption supports workloads where applications must guarantee that
1616
unauthorized parties, including server administrators, cannot read the
1717
encrypted data.
1818

19-
.. mongodoc:: client-side-field-level-encryption
19+
.. seealso:: The MongoDB documentation on `Client Side Field Level Encryption <https://dochub.mongodb.org/core/client-side-field-level-encryption>`_.
2020

2121
Dependencies
2222
------------

‎doc/examples/geo.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ Geospatial Indexing Example
1010
This example shows how to create and use a :data:`~pymongo.GEO2D`
1111
index in PyMongo. To create a spherical (earth-like) geospatial index use :data:`~pymongo.GEOSPHERE` instead.
1212

13-
.. mongodoc:: geo
13+
.. seealso:: The MongoDB documentation on `Geospatial Indexes <https://dochub.mongodb.org/core/geo>`_.
1414

1515
Creating a Geospatial Index
1616
---------------------------

‎doc/examples/high_availability.rst

+1-1
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ PyMongo makes working with `replica sets
1414
replica set and show how to handle both initialization and normal
1515
connections with PyMongo.
1616

17-
.. mongodoc:: rs
17+
.. seealso:: The MongoDB documentation on `replication <https://dochub.mongodb.org/core/rs>`_.
1818

1919
Starting a Replica Set
2020
~~~~~~~~~~~~~~~~~~~~~~

‎doc/make.bat

+35-113
Original file line numberDiff line numberDiff line change
@@ -1,113 +1,35 @@
1-
@ECHO OFF
2-
3-
REM Command file for Sphinx documentation
4-
5-
set SPHINXBUILD=sphinx-build
6-
set BUILDDIR=_build
7-
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
8-
if NOT "%PAPER%" == "" (
9-
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
10-
)
11-
12-
if "%1" == "" goto help
13-
14-
if "%1" == "help" (
15-
:help
16-
echo.Please use `make ^<target^>` where ^<target^> is one of
17-
echo. html to make standalone HTML files
18-
echo. dirhtml to make HTML files named index.html in directories
19-
echo. pickle to make pickle files
20-
echo. json to make JSON files
21-
echo. htmlhelp to make HTML files and a HTML help project
22-
echo. qthelp to make HTML files and a qthelp project
23-
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
24-
echo. changes to make an overview over all changed/added/deprecated items
25-
echo. linkcheck to check all external links for integrity
26-
echo. doctest to run all doctests embedded in the documentation if enabled
27-
goto end
28-
)
29-
30-
if "%1" == "clean" (
31-
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
32-
del /q /s %BUILDDIR%\*
33-
goto end
34-
)
35-
36-
if "%1" == "html" (
37-
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
38-
echo.
39-
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
40-
goto end
41-
)
42-
43-
if "%1" == "dirhtml" (
44-
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
45-
echo.
46-
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
47-
goto end
48-
)
49-
50-
if "%1" == "pickle" (
51-
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
52-
echo.
53-
echo.Build finished; now you can process the pickle files.
54-
goto end
55-
)
56-
57-
if "%1" == "json" (
58-
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
59-
echo.
60-
echo.Build finished; now you can process the JSON files.
61-
goto end
62-
)
63-
64-
if "%1" == "htmlhelp" (
65-
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
66-
echo.
67-
echo.Build finished; now you can run HTML Help Workshop with the ^
68-
.hhp project file in %BUILDDIR%/htmlhelp.
69-
goto end
70-
)
71-
72-
if "%1" == "qthelp" (
73-
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
74-
echo.
75-
echo.Build finished; now you can run "qcollectiongenerator" with the ^
76-
.qhcp project file in %BUILDDIR%/qthelp, like this:
77-
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\PyMongo.qhcp
78-
echo.To view the help file:
79-
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\PyMongo.ghc
80-
goto end
81-
)
82-
83-
if "%1" == "latex" (
84-
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
85-
echo.
86-
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
87-
goto end
88-
)
89-
90-
if "%1" == "changes" (
91-
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
92-
echo.
93-
echo.The overview file is in %BUILDDIR%/changes.
94-
goto end
95-
)
96-
97-
if "%1" == "linkcheck" (
98-
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
99-
echo.
100-
echo.Link check complete; look for any errors in the above output ^
101-
or in %BUILDDIR%/linkcheck/output.txt.
102-
goto end
103-
)
104-
105-
if "%1" == "doctest" (
106-
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
107-
echo.
108-
echo.Testing of doctests in the sources finished, look at the ^
109-
results in %BUILDDIR%/doctest/output.txt.
110-
goto end
111-
)
112-
113-
:end
1+
@ECHO OFF
2+
3+
pushd %~dp0
4+
5+
REM Command file for Sphinx documentation
6+
7+
if "%SPHINXBUILD%" == "" (
8+
set SPHINXBUILD=sphinx-build
9+
)
10+
set SOURCEDIR=.
11+
set BUILDDIR=_build
12+
13+
if "%1" == "" goto help
14+
15+
%SPHINXBUILD% >NUL 2>NUL
16+
if errorlevel 9009 (
17+
echo.
18+
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
19+
echo.installed, then set the SPHINXBUILD environment variable to point
20+
echo.to the full path of the 'sphinx-build' executable. Alternatively you
21+
echo.may add the Sphinx directory to PATH.
22+
echo.
23+
echo.If you don't have Sphinx installed, grab it from
24+
echo.http://sphinx-doc.org/
25+
exit /b 1
26+
)
27+
28+
%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
29+
goto end
30+
31+
:help
32+
%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
33+
34+
:end
35+
popd

0 commit comments

Comments
 (0)