Skip to content
This repository was archived by the owner on Nov 3, 2023. It is now read-only.

Commit 4626bc1

Browse files
NurdokNurdok
committed
Merge pull request #100 from Nurdok/realdocs
Working on real documentation using Sphinx.
2 parents a5aa2e2 + edc4209 commit 4626bc1

15 files changed

+940
-129
lines changed

‎README.rst

Lines changed: 10 additions & 129 deletions
Original file line numberDiff line numberDiff line change
@@ -10,149 +10,30 @@ custom checks can be easily added, for example to cover
1010
NumPy `docstring conventions
1111
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_.
1212

13-
Installation
14-
-----------------------------------------------------------
13+
**pep257** supports Python 2.6, 2.7, 3.2, 3.3, 3.4, pypy and pypy3.
1514

16-
Use `pip <http://pip-installer.org>`_ or easy_install::
15+
Quick Start
16+
-----------
1717

18-
pip install pep257
18+
Install
19+
^^^^^^^
1920

20-
Alternatively, you can use ``pep257.py`` source file
21-
directly--it is self-contained.
21+
.. code::
2222
23-
**pep257** is tested with Python 2.6, 2.7, 3.2, 3.3, 3.4, pypy and pypy3.
23+
pip install pep257
2424
25-
Example
26-
-----------------------------------------------------------
25+
Run
26+
^^^
2727

2828
.. code::
2929
30-
$ pep257 --help
31-
Usage: pep257 [options] [<file|dir>...]
32-
33-
Options:
34-
--version show program's version number and exit
35-
-h, --help show this help message and exit
36-
-e, --explain show explanation of each error
37-
-s, --source show source for each error
38-
--ignore=<codes> ignore a list comma-separated error codes, for
39-
example: --ignore=D101,D202
40-
--match=<pattern> check only files that exactly match <pattern> regular
41-
expression; default is --match='(?!test_).*\.py' which
42-
matches files that don't start with 'test_' but end
43-
with '.py'
44-
--match-dir=<pattern>
45-
search only dirs that exactly match <pattern> regular
46-
expression; default is --match-dir='[^\.].*', which
47-
matches all dirs that don't start with a dot
48-
-d, --debug print debug information
49-
-v, --verbose print status information
50-
--count print total number of errors to stdout
51-
5230
$ pep257 test.py
5331
test.py:18 in private nested class `meta`:
5432
D101: Docstring missing
5533
test.py:22 in public method `method`:
5634
D102: Docstring missing
5735
...
5836
59-
$ pep257 test.py --explain
60-
test.py:18 in private nested class `meta`:
61-
D101: Docstring missing
62-
63-
All modules should normally have docstrings. [...] all functions and
64-
classes exported by a module should also have docstrings. Public
65-
methods (including the __init__ constructor) should also have
66-
docstrings.
67-
68-
Note: Public (exported) definitions are either those with names listed
69-
in __all__ variable (if present), or those that do not start
70-
with a single underscore.
71-
...
72-
73-
$ pep257 test.py --source
74-
test.py:15 in public class `class_`:
75-
D101: Docstring missing
76-
77-
15: class class_:
78-
16:
79-
...
80-
81-
$ pep257 test.py --count
82-
test.py:18 in private nested class `meta`:
83-
D101: Docstring missing
84-
test.py:22 in public method `method`:
85-
D102: Docstring missing
86-
...
87-
33
88-
89-
90-
Error codes
91-
-----------------------------------------------------------
92-
93-
All **pep257** errors have unique codes. All codes start with a capital D and
94-
are grouped as follows:
95-
96-
+--------------+--------------------------------------------------------------+
97-
| **Missing docstrings** |
98-
+--------------+--------------------------------------------------------------+
99-
| D10{0,1,2,3} | Public {module,class,method,function} missing. |
100-
+--------------+--------------------------------------------------------------+
101-
| **Whitespace issues** |
102-
+--------------+--------------------------------------------------------------+
103-
| D200 | One-line docstrings should fit on one line with quotes. |
104-
+--------------+--------------------------------------------------------------+
105-
| D20{1,2} | No blank lines allowed {before,after} docstring. |
106-
+--------------+--------------------------------------------------------------+
107-
| D20{3,4} | 1 blank required {before,after} class docstring. |
108-
+--------------+--------------------------------------------------------------+
109-
| D205 | Blank line required between one-line summary and description.|
110-
+--------------+--------------------------------------------------------------+
111-
| D206 | Docstring should be indented with spaces, not tabs. |
112-
+--------------+--------------------------------------------------------------+
113-
| D20{7,8} | Docstring {under,over}-indented. |
114-
+--------------+--------------------------------------------------------------+
115-
| D209 | Put multi-line docstring closing quotes on separate line. |
116-
+--------------+--------------------------------------------------------------+
117-
| D210 | No whitespaces allowed surrounding docstring text. |
118-
+--------------+--------------------------------------------------------------+
119-
| **Quotes issues** |
120-
+--------------+--------------------------------------------------------------+
121-
| D300 | Use """triple double quotes""". |
122-
+--------------+--------------------------------------------------------------+
123-
| D301 | Use r""" if any backslashes in your docstring. |
124-
+--------------+--------------------------------------------------------------+
125-
| D302 | Use u""" for Unicode docstrings (Python 2 only). |
126-
+--------------+--------------------------------------------------------------+
127-
| **Docstring content issues** |
128-
+--------------+--------------------------------------------------------------+
129-
| D400 | First line should end with a period. |
130-
+--------------+--------------------------------------------------------------+
131-
| D401 | First line should be in imperative mood. |
132-
+--------------+--------------------------------------------------------------+
133-
| D402 | First line should not be the function's "signature". |
134-
+--------------+--------------------------------------------------------------+
135-
136-
Configuration
137-
-----------------------------------------------------------
138-
``pep257`` looks for a config file in the root of the project (the common
139-
prefix of all checked files) and goes up in the directory tree until it finds
140-
one of the following files (in this order):
141-
142-
* ``setup.cfg``
143-
* ``tox.ini``
144-
* ``.pep257``
145-
146-
The first found file is read, and configurations in the ``[pep257]`` section
147-
are used, if such a section exists.
148-
149-
Config Example
150-
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
151-
152-
.. code::
15337
154-
[pep257]
155-
verbose = true
156-
ignore = D100,D203,D405
157-
explain = true
38+
`Read the full documentation here <http://pep257.readthedocs.org>`_.
15839

‎docs/Makefile

Lines changed: 177 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,177 @@
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+
52+
html:
53+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
54+
@echo
55+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
56+
57+
dirhtml:
58+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
59+
@echo
60+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
61+
62+
singlehtml:
63+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
64+
@echo
65+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
66+
67+
pickle:
68+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
69+
@echo
70+
@echo "Build finished; now you can process the pickle files."
71+
72+
json:
73+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
74+
@echo
75+
@echo "Build finished; now you can process the JSON files."
76+
77+
htmlhelp:
78+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
79+
@echo
80+
@echo "Build finished; now you can run HTML Help Workshop with the" \
81+
".hhp project file in $(BUILDDIR)/htmlhelp."
82+
83+
qthelp:
84+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
85+
@echo
86+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
87+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
88+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/pep257.qhcp"
89+
@echo "To view the help file:"
90+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/pep257.qhc"
91+
92+
devhelp:
93+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
94+
@echo
95+
@echo "Build finished."
96+
@echo "To view the help file:"
97+
@echo "# mkdir -p $$HOME/.local/share/devhelp/pep257"
98+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/pep257"
99+
@echo "# devhelp"
100+
101+
epub:
102+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
103+
@echo
104+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
105+
106+
latex:
107+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
108+
@echo
109+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
110+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
111+
"(use \`make latexpdf' here to do that automatically)."
112+
113+
latexpdf:
114+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
115+
@echo "Running LaTeX files through pdflatex..."
116+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
117+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
118+
119+
latexpdfja:
120+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
121+
@echo "Running LaTeX files through platex and dvipdfmx..."
122+
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
123+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
124+
125+
text:
126+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
127+
@echo
128+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
129+
130+
man:
131+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
132+
@echo
133+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
134+
135+
texinfo:
136+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
137+
@echo
138+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
139+
@echo "Run \`make' in that directory to run these through makeinfo" \
140+
"(use \`make info' here to do that automatically)."
141+
142+
info:
143+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
144+
@echo "Running Texinfo files through makeinfo..."
145+
make -C $(BUILDDIR)/texinfo info
146+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
147+
148+
gettext:
149+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
150+
@echo
151+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
152+
153+
changes:
154+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
155+
@echo
156+
@echo "The overview file is in $(BUILDDIR)/changes."
157+
158+
linkcheck:
159+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
160+
@echo
161+
@echo "Link check complete; look for any errors in the above output " \
162+
"or in $(BUILDDIR)/linkcheck/output.txt."
163+
164+
doctest:
165+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
166+
@echo "Testing of doctests in the sources finished, look at the " \
167+
"results in $(BUILDDIR)/doctest/output.txt."
168+
169+
xml:
170+
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
171+
@echo
172+
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
173+
174+
pseudoxml:
175+
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
176+
@echo
177+
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

0 commit comments

Comments
 (0)