Skip to content

DOC: Move content in doc/README.rst to doc/source/contributing.rst #23840

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 7 commits into from
Nov 27, 2018
Merged

DOC: Move content in doc/README.rst to doc/source/contributing.rst #23840

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
c98e523
23828 moved content to contributing, and updated rebase command to merge
KimiJL Nov 21, 2018
211c96f
23828 added a missing period
KimiJL Nov 21, 2018
4b8e2e1
23828 cleaned up outdated documentation and README
KimiJL Nov 21, 2018
a2fbaa3
23828 removed a link in README
KimiJL Nov 21, 2018
fcd7e6c
reset contributing.rst
KimiJL Nov 21, 2018
a8966b8
23828 change README to link
KimiJL Nov 26, 2018
4872a62
Update doc/README.rst
datapythonista Nov 26, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
155 changes: 3 additions & 152 deletions doc/README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,161 +3,12 @@
Contributing to the documentation
=================================

Whether you are someone who loves writing, teaching, or development,
contributing to the documentation is a huge value. If you don't see yourself
as a developer type, please don't stress and know that we want you to
contribute. You don't even have to be an expert on *pandas* to do so!
Something as simple as rewriting small passages for clarity
as you reference the docs is a simple but effective way to contribute. The
next person to read that passage will be in your debt!

Actually, there are sections of the docs that are worse off by being written
by experts. If something in the docs doesn't make sense to you, updating the
relevant section after you figure it out is a simple way to ensure it will
help the next person.

.. contents:: Table of contents:
:local:


About the pandas documentation
------------------------------

The documentation is written in **reStructuredText**, which is almost like writing
in plain English, and built using `Sphinx <http://sphinx.pocoo.org/>`__. The
Sphinx Documentation has an excellent `introduction to reST
<http://sphinx.pocoo.org/rest.html>`__. Review the Sphinx docs to perform more
complex changes to the documentation as well.

Some other important things to know about the docs:

- The pandas documentation consists of two parts: the docstrings in the code
itself and the docs in this folder ``pandas/doc/``.

The docstrings provide a clear explanation of the usage of the individual
functions, while the documentation in this folder consists of tutorial-like
overviews per topic together with some other information (what's new,
installation, etc).

- The docstrings follow the **Numpy Docstring Standard** which is used widely
in the Scientific Python community. This standard specifies the format of
the different sections of the docstring. See `this document
<https://numpydoc.readthedocs.io/en/latest/>`_
for a detailed explanation, or look at some of the existing functions to
extend it in a similar manner.

- The tutorials make heavy use of the `ipython directive
<http://matplotlib.org/sampledoc/ipython_directive.html>`_ sphinx extension.
This directive lets you put code in the documentation which will be run
during the doc build. For example:

::

.. ipython:: python

x = 2
x**3

will be rendered as

::

In [1]: x = 2

In [2]: x**3
Out[2]: 8

This means that almost all code examples in the docs are always run (and the
output saved) during the doc build. This way, they will always be up to date,
but it makes the doc building a bit more complex.


How to build the pandas documentation
-------------------------------------

Requirements
^^^^^^^^^^^^

To build the pandas docs there are some extra requirements: you will need to
have ``sphinx`` and ``ipython`` installed. `numpydoc
<https://github.com/numpy/numpydoc>`_ is used to parse the docstrings that
follow the Numpy Docstring Standard (see above), but you don't need to install
this because a local copy of ``numpydoc`` is included in the pandas source
code. `nbsphinx <https://nbsphinx.readthedocs.io/>`_ is used to convert
Jupyter notebooks. You will need to install it if you intend to modify any of
the notebooks included in the documentation.

Furthermore, it is recommended to have all `optional dependencies
<http://pandas.pydata.org/pandas-docs/dev/install.html#optional-dependencies>`_
installed. This is not needed, but be aware that you will see some error
messages. Because all the code in the documentation is executed during the doc
build, the examples using this optional dependencies will generate errors.
Run ``pd.show_versions()`` to get an overview of the installed version of all
dependencies.

.. warning::

Sphinx version >= 1.2.2 or the older 1.1.3 is required.

Building pandas
^^^^^^^^^^^^^^^

For a step-by-step overview on how to set up your environment, to work with
the pandas code and git, see `the developer pages
<http://pandas.pydata.org/developers.html#working-with-the-code>`_.
When you start to work on some docs, be sure to update your code to the latest
development version ('master')::

git fetch upstream
git rebase upstream/master

Often it will be necessary to rebuild the C extension after updating::

python setup.py build_ext --inplace

Building the documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^

So how do you build the docs? Navigate to your local folder
``pandas/doc/`` directory in the console and run::

python make.py html

And then you can find the html output in the folder ``pandas/doc/build/html/``.

The first time it will take quite a while, because it has to run all the code
examples in the documentation and build all generated docstring pages.
In subsequent evocations, sphinx will try to only build the pages that have
been modified.

If you want to do a full clean build, do::

python make.py clean
python make.py build


Starting with 0.13.1 you can tell ``make.py`` to compile only a single section
of the docs, greatly reducing the turn-around time for checking your changes.
You will be prompted to delete `.rst` files that aren't required, since the
last committed version can always be restored from git.

::

#omit autosummary and API section
python make.py clean
python make.py --no-api

# compile the docs with only a single
# section, that which is in indexing.rst
python make.py clean
python make.py --single indexing

For comparison, a full doc build may take 10 minutes. a ``-no-api`` build
may take 3 minutes and a single section may take 15 seconds.

Where to start?
---------------

Please follow the documentation in ``doc/source/contributing.rst`` for a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd remove the titles, and paragraphs and leave something as simple as:

See `doc/source/contributing.rst` in this repo, or the generated html version https://pandas.pydata.org/pandas-docs/stable/contributing.html

Not a big difference, but leaving the titles and some info gives the wrong impression that this is a page (that could be extended) instead of a "redirect".

detailed guide on how to contribute to documentation.

There are a number of issues listed under `Docs
<https://github.com/pandas-dev/pandas/issues?labels=Docs&sort=updated&state=open>`_
and `good first issue
Expand Down
63 changes: 54 additions & 9 deletions doc/source/contributing.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -258,13 +258,18 @@ you created the branch, check the section on
Contributing to the documentation
=================================

Contributing to the documentation benefits everyone who uses *pandas*.
We encourage you to help us improve the documentation, and
you don't have to be an expert on *pandas* to do so! In fact,
there are sections of the docs that are worse off after being written by
experts. If something in the docs doesn't make sense to you, updating the
relevant section after you figure it out is a great way to ensure it will help
the next person.
Whether you are someone who loves writing, teaching, or development,
contributing to the documentation is a huge value. If you don't see yourself
as a developer type, please don't stress and know that we want you to
contribute. You don't even have to be an expert on *pandas* to do so!
Something as simple as rewriting small passages for clarity
as you reference the docs is a simple but effective way to contribute. The
next person to read that passage will be in your debt!

Actually, there are sections of the docs that are worse off by being written
by experts. If something in the docs doesn't make sense to you, updating the
relevant section after you figure it out is a simple way to ensure it will
help the next person.

.. contents:: Documentation:
:local:
Expand Down Expand Up @@ -394,6 +399,43 @@ Requirements
First, you need to have a development environment to be able to build pandas
(see the docs on :ref:`creating a development environment above <contributing.dev_env>`).

To build the pandas docs there are some extra requirements: you will need to
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this is very duplicative, Creating a Python Environment.

have ``sphinx`` and ``ipython`` installed. `numpydoc
<https://github.com/numpy/numpydoc>`_ is used to parse the docstrings that
follow the Numpy Docstring Standard (see above), but you don't need to install
this because a local copy of ``numpydoc`` is included in the pandas source
code. `nbsphinx <https://nbsphinx.readthedocs.io/>`_ is used to convert
Jupyter notebooks. You will need to install it if you intend to modify any of
the notebooks included in the documentation.

Furthermore, it is recommended to have all `optional dependencies
<http://pandas.pydata.org/pandas-docs/dev/install.html#optional-dependencies>`_
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can remove this paragraph, the optional dependencies file doesn't exist anymore, there is just a dependencies file now.

installed. This is not needed, but be aware that you will see some error
messages. Because all the code in the documentation is executed during the doc
build, the examples using this optional dependencies will generate errors.
Run ``pd.show_versions()`` to get an overview of the installed version of all
dependencies.

.. warning::

Sphinx version >= 1.2.2 or the older 1.1.3 is required.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can remove the warning, I don't think that's true anymore, and in any cases, those versions are old enough to assume everybody uses something more modern.


Building pandas
^^^^^^^^^^^^^^^

For a step-by-step overview on how to set up your environment, to work with
the pandas code and git, see `the developer pages
<http://pandas.pydata.org/developers.html#working-with-the-code>`_.
When you start to work on some docs, be sure to update your code to the latest
development version ('master')::

git fetch upstream
git merge upstream/master

Often it will be necessary to rebuild the C extension after updating::

python setup.py build_ext --inplace

Building the documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~

Expand All @@ -413,8 +455,11 @@ If you want to do a full clean build, do::
python make.py clean
python make.py html

You can tell ``make.py`` to compile only a single section of the docs, greatly
reducing the turn-around time for checking your changes.

Starting with 0.13.1 you can tell ``make.py`` to compile only a single section
of the docs, greatly reducing the turn-around time for checking your changes.
You will be prompted to delete `.rst` files that aren't required, since the
last committed version can always be restored from git.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You can delete those two last lines, that's not true anymore. Also the Starting with 0.13.1, that version is from 2015, I think we can assume nobody is using it anymore.


::

Expand Down