From c98e523ac73f81192abebac1e66bc29da1718ee2 Mon Sep 17 00:00:00 2001 From: KimiJL Date: Wed, 21 Nov 2018 09:16:31 -0500 Subject: [PATCH 1/7] 23828 moved content to contributing, and updated rebase command to merge --- doc/README.rst | 155 +----------------------------------- doc/source/contributing.rst | 63 ++++++++++++--- 2 files changed, 57 insertions(+), 161 deletions(-) diff --git a/doc/README.rst b/doc/README.rst index 12950d323f5d3..0293b3cf09bec 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -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 `__. The -Sphinx Documentation has an excellent `introduction to reST -`__. 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 - `_ - 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 - `_ 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 -`_ 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 `_ 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 -`_ -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 -`_. -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 +detailed guide on how to contribute to documentation + There are a number of issues listed under `Docs `_ and `good first issue diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 6fdb5bdbb6b1d..dc423e3c560fe 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -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: @@ -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 `). +To build the pandas docs there are some extra requirements: you will need to +have ``sphinx`` and ``ipython`` installed. `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 `_ 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 +`_ +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 +`_. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -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. :: From 211c96fe132bbbd28a219b34c3daad2a4c9d011a Mon Sep 17 00:00:00 2001 From: KimiJL Date: Wed, 21 Nov 2018 09:28:45 -0500 Subject: [PATCH 2/7] 23828 added a missing period --- doc/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.rst b/doc/README.rst index 0293b3cf09bec..3575e0e1b4cd9 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -7,7 +7,7 @@ Where to start? --------------- Please follow the documentation in ``doc/source/contributing.rst`` for a -detailed guide on how to contribute to documentation +detailed guide on how to contribute to documentation. There are a number of issues listed under `Docs `_ From 4b8e2e1f192bb75fdc714ace7ddf7e1109b26ea4 Mon Sep 17 00:00:00 2001 From: KimiJL Date: Wed, 21 Nov 2018 11:37:12 -0500 Subject: [PATCH 3/7] 23828 cleaned up outdated documentation and README --- doc/README.rst | 23 +---------------------- doc/source/contributing.rst | 19 ++----------------- 2 files changed, 3 insertions(+), 39 deletions(-) diff --git a/doc/README.rst b/doc/README.rst index 3575e0e1b4cd9..113cd5c9ed1ea 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1,24 +1,3 @@ .. _contributing.docs: -Contributing to the documentation -================================= - -Where to start? ---------------- - -Please follow the documentation in ``doc/source/contributing.rst`` for a -detailed guide on how to contribute to documentation. - -There are a number of issues listed under `Docs -`_ -and `good first issue -`_ -where you could start out. - -Or maybe you have an idea of your own, by using pandas, looking for something -in the documentation and thinking 'this can be improved', let's do something -about that! - -Feel free to ask questions on `mailing list -`_ or submit an -issue on Github. +See `doc/source/contributing.rst` in this repo, or the generated html version https://pandas.pydata.org/pandas-docs/stable/contributing.html \ No newline at end of file diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index dc423e3c560fe..153d968891145 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -408,18 +408,6 @@ code. `nbsphinx `_ 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 -`_ -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 ^^^^^^^^^^^^^^^ @@ -455,11 +443,8 @@ If you want to do a full clean build, do:: python make.py clean python make.py html - -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. +You can tell ``make.py`` to compile only a single section of the docs, greatly +reducing the turn-around time for checking your changes. :: From a2fbaa357b1d4e7be10acee0d7d5ed47c379d325 Mon Sep 17 00:00:00 2001 From: KimiJL Date: Wed, 21 Nov 2018 11:45:23 -0500 Subject: [PATCH 4/7] 23828 removed a link in README --- doc/README.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/doc/README.rst b/doc/README.rst index 113cd5c9ed1ea..3e7d49d345609 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1,3 +1 @@ -.. _contributing.docs: - See `doc/source/contributing.rst` in this repo, or the generated html version https://pandas.pydata.org/pandas-docs/stable/contributing.html \ No newline at end of file From fcd7e6c2207c507b42cf767963aeb0ada0c05480 Mon Sep 17 00:00:00 2001 From: KimiJL Date: Wed, 21 Nov 2018 15:14:57 -0500 Subject: [PATCH 5/7] reset contributing.rst --- doc/source/contributing.rst | 44 ++++++------------------------------- 1 file changed, 7 insertions(+), 37 deletions(-) diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 153d968891145..6fdb5bdbb6b1d 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -258,18 +258,13 @@ you created the branch, check the section on 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. +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. .. contents:: Documentation: :local: @@ -399,31 +394,6 @@ 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 `). -To build the pandas docs there are some extra requirements: you will need to -have ``sphinx`` and ``ipython`` installed. `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 `_ 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. - -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 -`_. -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 ~~~~~~~~~~~~~~~~~~~~~~~~~~ From a8966b886dd4189a3cb4adc12d6ee78441abfb9a Mon Sep 17 00:00:00 2001 From: KimiJL Date: Mon, 26 Nov 2018 07:35:36 -0500 Subject: [PATCH 6/7] 23828 change README to link --- doc/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.rst b/doc/README.rst index 3e7d49d345609..d8a627c95bc22 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1 +1 @@ -See `doc/source/contributing.rst` in this repo, or the generated html version https://pandas.pydata.org/pandas-docs/stable/contributing.html \ No newline at end of file +See [contributing.rst](https://github.com/pandas-dev/pandas/blob/master/doc/source/contributing.rst) in this repo. \ No newline at end of file From 4872a624103f48c62a02964b2525197151df2dfb Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Mon, 26 Nov 2018 09:58:53 -0500 Subject: [PATCH 7/7] Update doc/README.rst Co-Authored-By: KimiJL --- doc/README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/README.rst b/doc/README.rst index d8a627c95bc22..a11ed8d9d03e3 100644 --- a/doc/README.rst +++ b/doc/README.rst @@ -1 +1 @@ -See [contributing.rst](https://github.com/pandas-dev/pandas/blob/master/doc/source/contributing.rst) in this repo. \ No newline at end of file +See `contributing.rst `_ in this repo.