Skip to content

Commit 9efcb03

Browse files
jorisvandenbosschejorisvandenbossche
committed
Merge pull request #5996 from jorisvandenbossche/doc-guide
DOC: add guidelines for building the docs
2 parents 2ccd74d + 972c209 commit 9efcb03

File tree

3 files changed

+157
-0
lines changed

3 files changed

+157
-0
lines changed

‎doc/README.rst

+151
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,151 @@
1+
.. _contributing.docs:
2+
3+
Contributing to the documentation
4+
=================================
5+
6+
If you're not the developer type, contributing to the documentation is still
7+
of huge value. You don't even have to be an expert on
8+
*pandas* to do so! Something as simple as rewriting small passages for clarity
9+
as you reference the docs is a simple but effective way to contribute. The
10+
next person to read that passage will be in your debt!
11+
12+
Actually, there are sections of the docs that are worse off by being written
13+
by experts. If something in the docs doesn't make sense to you, updating the
14+
relevant section after you figure it out is a simple way to ensure it will
15+
help the next person.
16+
17+
.. contents:: Table of contents:
18+
:local:
19+
20+
21+
About the pandas documentation
22+
------------------------------
23+
24+
The documentation is written in **reStructuredText**, which is almost like writing
25+
in plain English, and built using `Sphinx <http://sphinx.pocoo.org/>`__. The
26+
Sphinx Documentation has an excellent `introduction to reST
27+
<http://sphinx.pocoo.org/rest.html>`__. Review the Sphinx docs to perform more
28+
complex changes to the documentation as well.
29+
30+
Some other important things to know about the docs:
31+
32+
- The pandas documentation consists of two parts: the docstrings in the code
33+
itself and the docs in this folder ``pandas/doc/``.
34+
35+
The docstrings provide a clear explanation of the usage of the individual
36+
functions, while the documentation in this filder consists of tutorial-like
37+
overviews per topic together with some other information (whatsnew,
38+
installation, etc).
39+
40+
- The docstrings follow the **Numpy Docstring Standard** which is used widely
41+
in the Scientific Python community. This standard specifies the format of
42+
the different sections of the docstring. See `this document
43+
<https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_
44+
for a detailed explanation, or look at some of the existing functions to
45+
extend it in a similar manner.
46+
47+
- The tutorials make heavy use of the `ipython directive
48+
<http://matplotlib.org/sampledoc/ipython_directive.html>`_ sphinx extension.
49+
This directive lets you put code in the documentation which will be run
50+
during the doc build. For example:
51+
52+
::
53+
54+
.. ipython:: python
55+
56+
x = 2
57+
x**3
58+
59+
will be renderd as
60+
61+
::
62+
63+
In [1]: x = 2
64+
65+
In [2]: x**3
66+
Out[2]: 8
67+
68+
This means that almost all code examples in the docs are always run (and the
69+
ouptut saved) during the doc build. This way, they will always be up to date,
70+
but it makes the doc building a bit more complex.
71+
72+
73+
How to build the pandas documentation
74+
-------------------------------------
75+
76+
Requirements
77+
^^^^^^^^^^^^
78+
79+
To build the pandas docs there are some extra requirements: you will need to
80+
have ``sphinx`` and ``ipython`` installed. `numpydoc
81+
<https://github.com/numpy/numpydoc>`_ is used to parse the docstrings that
82+
follow the Numpy Docstring Standard (see above), but you don't need to install
83+
this because a local copy of ``numpydoc`` is included in the pandas source
84+
code.
85+
86+
Furthermore, it is recommended to have all `optional dependencies
87+
<http://pandas.pydata.org/pandas-docs/dev/install.html#optional-dependencies>`_
88+
installed. This is not needed, but be aware that you will see some error
89+
messages. Because all the code in the documentation is executed during the doc
90+
build, the examples using this optional dependencies will generate errors.
91+
Run ``pd.show_version()`` to get an overview of the installed version of all
92+
dependencies.
93+
94+
.. warning::
95+
96+
Building the docs with Sphinx version 1.2 is broken. Use the
97+
latest stable version (1.2.1) or the older 1.1.3.
98+
99+
Building pandas
100+
^^^^^^^^^^^^^^^
101+
102+
For a step-by-step overview on how to set up your environment, to work with
103+
the pandas code and git, see `the developer pages
104+
<http://pandas.pydata.org/developers.html#working-with-the-code>`_.
105+
When you start to work on some docs, be sure to update your code to the latest
106+
development version ('master')::
107+
108+
git fetch upstream
109+
git rebase upstream/master
110+
111+
Often it will be necessary to rebuild the C extension after updating::
112+
113+
python setup.py build_ext --inplace
114+
115+
Building the documentation
116+
^^^^^^^^^^^^^^^^^^^^^^^^^^
117+
118+
So how do you build the docs? Navigate to your local the folder
119+
``pandas/doc/`` directory in the console and run::
120+
121+
python make.py html
122+
123+
And then you can find the html output in the folder ``pandas/doc/build/html/``.
124+
125+
The first time it will take quite a while, because it has to run all the code
126+
examples in the documentation and build all generated docstring pages.
127+
In subsequent evocations, sphinx will try to only build the pages that have
128+
been modified.
129+
130+
If you want to do a full clean build, do::
131+
132+
python make.py clean
133+
python make.py build
134+
135+
136+
Where to start?
137+
---------------
138+
139+
There are a number of issues listed under `Docs
140+
<https://github.com/pydata/pandas/issues?labels=Docs&sort=updated&state=open>`_
141+
and `Good as first PR
142+
<https://github.com/pydata/pandas/issues?labels=Good+as+first+PR&sort=updated&state=open>`_
143+
where you could start out.
144+
145+
Or maybe you have an idea of you own, by using pandas, looking for something
146+
in the documentation and thinking 'this can be improved', let's do something
147+
about that!
148+
149+
Feel free to ask questions on `mailing list
150+
<https://groups.google.com/forum/?fromgroups#!forum/pydata>`_ or submit an
151+
issue on Github.

‎doc/source/contributing.rst

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
**********************
2+
Contributing to pandas
3+
**********************
4+
5+
.. include:: ../README.rst

‎doc/source/index.rst

+1
Original file line numberDiff line numberDiff line change
@@ -137,4 +137,5 @@ See the package overview for more detail about what's in the library.
137137
comparison_with_r
138138
comparison_with_sql
139139
api
140+
contributing
140141
release

0 commit comments

Comments
 (0)