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