Skip to content

Commit 349adb2

Browse files
pvpv
authored
Merge pull request #118 from jnothman/doc
Basic docs for numpydoc
2 parents 565f8a4 + 3213701 commit 349adb2

File tree

13 files changed

+1548
-39
lines changed

13 files changed

+1548
-39
lines changed

‎.gitmodules

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
[submodule "doc/scipy-sphinx-theme"]
2+
path = doc/scipy-sphinx-theme
3+
url = https://github.com/scipy/scipy-sphinx-theme

‎.travis.yml

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,3 +20,7 @@ script:
2020
cd dist
2121
pip install numpydoc* -v
2222
- nosetests numpydoc
23+
- |
24+
cd ../doc
25+
make html
26+
make latexpdf

‎README.rst

Lines changed: 8 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
.. image:: https://travis-ci.org/numpy/numpydoc.png?branch=master
22
:target: https://travis-ci.org/numpy/numpydoc/
33

4+
.. |docs| image:: https://readthedocs.org/projects/numpydoc/badge/?version=latest
5+
:alt: Documentation Status
6+
:scale: 100%
7+
:target: https://numpydoc.readthedocs.io/en/latest/?badge=latest
8+
9+
410
=====================================
511
numpydoc -- Numpy's Sphinx extensions
612
=====================================
@@ -13,45 +19,8 @@ The ``numpydoc`` extension provides support for the Numpy docstring format in
1319
Sphinx, and adds the code description directives ``np:function``,
1420
``np-c:function``, etc. that support the Numpy docstring syntax.
1521

16-
See `A Guide to NumPy/SciPy Documentation <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
17-
for how to write docs that use this extension.
18-
19-
20-
numpydoc
21-
========
22+
See `numpydoc docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_
23+
for how to write docs that use this extension, and the `user guide <https://numpydoc.readthedocs.io>`_
2224

2325
Numpydoc inserts a hook into Sphinx's autodoc that converts docstrings
2426
following the Numpy/Scipy format to a form palatable to Sphinx.
25-
26-
Options
27-
-------
28-
29-
The following options can be set in conf.py:
30-
31-
- ``numpydoc_use_plots``: bool
32-
33-
Whether to produce ``plot::`` directives for Examples sections that
34-
contain ``import matplotlib``.
35-
36-
- ``numpydoc_show_class_members``: bool
37-
38-
Whether to show all members of a class in the Methods and Attributes
39-
sections automatically.
40-
``True`` by default.
41-
42-
- ``numpydoc_show_inherited_class_members``: bool
43-
44-
Whether to show all inherited members of a class in the Methods and Attributes
45-
sections automatically. If it's false, inherited members won't shown.
46-
``True`` by default.
47-
48-
- ``numpydoc_class_members_toctree``: bool
49-
50-
Whether to create a Sphinx table of contents for the lists of class
51-
methods and attributes. If a table of contents is made, Sphinx expects
52-
each entry to have a separate page.
53-
``True`` by default.
54-
55-
- ``numpydoc_edit_link``: bool (DEPRECATED -- edit your HTML template instead)
56-
57-
Whether to insert an edit link after docstrings.

‎doc/Makefile

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
BUILDDIR = _build
9+
10+
# User-friendly check for sphinx-build
11+
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
12+
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
13+
endif
14+
15+
# Internal variables.
16+
PAPEROPT_a4 = -D latex_paper_size=a4
17+
PAPEROPT_letter = -D latex_paper_size=letter
18+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
19+
# the i18n builder cannot share the environment and doctrees with the others
20+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
21+
22+
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
23+
24+
help:
25+
@echo "Please use \`make <target>' where <target> is one of"
26+
@echo " html to make standalone HTML files"
27+
@echo " dirhtml to make HTML files named index.html in directories"
28+
@echo " singlehtml to make a single large HTML file"
29+
@echo " pickle to make pickle files"
30+
@echo " json to make JSON files"
31+
@echo " htmlhelp to make HTML files and a HTML help project"
32+
@echo " qthelp to make HTML files and a qthelp project"
33+
@echo " devhelp to make HTML files and a Devhelp project"
34+
@echo " epub to make an epub"
35+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
36+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
37+
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
38+
@echo " text to make text files"
39+
@echo " man to make manual pages"
40+
@echo " texinfo to make Texinfo files"
41+
@echo " info to make Texinfo files and run them through makeinfo"
42+
@echo " gettext to make PO message catalogs"
43+
@echo " changes to make an overview of all changed/added/deprecated items"
44+
@echo " xml to make Docutils-native XML files"
45+
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
46+
@echo " linkcheck to check all external links for integrity"
47+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
48+
49+
clean:
50+
-rm -rf $(BUILDDIR)/*
51+
-rm -rf auto_examples/
52+
-rm -rf generated/*
53+
-rm -rf modules/generated/*
54+
55+
html:
56+
# These two lines make the build a bit more lengthy, and the
57+
# the embedding of images more robust
58+
rm -rf $(BUILDDIR)/html/_images
59+
#rm -rf _build/doctrees/
60+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
61+
@echo
62+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
63+
64+
dirhtml:
65+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
66+
@echo
67+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
68+
69+
singlehtml:
70+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
71+
@echo
72+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
73+
74+
pickle:
75+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
76+
@echo
77+
@echo "Build finished; now you can process the pickle files."
78+
79+
json:
80+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
81+
@echo
82+
@echo "Build finished; now you can process the JSON files."
83+
84+
htmlhelp:
85+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
86+
@echo
87+
@echo "Build finished; now you can run HTML Help Workshop with the" \
88+
".hhp project file in $(BUILDDIR)/htmlhelp."
89+
90+
qthelp:
91+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
92+
@echo
93+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
94+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
95+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/project-template.qhcp"
96+
@echo "To view the help file:"
97+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/project-template.qhc"
98+
99+
devhelp:
100+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
101+
@echo
102+
@echo "Build finished."
103+
@echo "To view the help file:"
104+
@echo "# mkdir -p $$HOME/.local/share/devhelp/project-template"
105+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/project-template"
106+
@echo "# devhelp"
107+
108+
epub:
109+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
110+
@echo
111+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
112+
113+
latex:
114+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115+
@echo
116+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
117+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
118+
"(use \`make latexpdf' here to do that automatically)."
119+
120+
latexpdf:
121+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
122+
@echo "Running LaTeX files through pdflatex..."
123+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
124+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
125+
126+
latexpdfja:
127+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
128+
@echo "Running LaTeX files through platex and dvipdfmx..."
129+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
130+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
131+
132+
text:
133+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
134+
@echo
135+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
136+
137+
man:
138+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
139+
@echo
140+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
141+
142+
texinfo:
143+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144+
@echo
145+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
146+
@echo "Run \`make' in that directory to run these through makeinfo" \
147+
"(use \`make info' here to do that automatically)."
148+
149+
info:
150+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
151+
@echo "Running Texinfo files through makeinfo..."
152+
make -C $(BUILDDIR)/texinfo info
153+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
154+
155+
gettext:
156+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
157+
@echo
158+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
159+
160+
changes:
161+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
162+
@echo
163+
@echo "The overview file is in $(BUILDDIR)/changes."
164+
165+
linkcheck:
166+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
167+
@echo
168+
@echo "Link check complete; look for any errors in the above output " \
169+
"or in $(BUILDDIR)/linkcheck/output.txt."
170+
171+
doctest:
172+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
173+
@echo "Testing of doctests in the sources finished, look at the " \
174+
"results in $(BUILDDIR)/doctest/output.txt."
175+
176+
xml:
177+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
178+
@echo
179+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
180+
181+
pseudoxml:
182+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
183+
@echo
184+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

0 commit comments

Comments
 (0)