From 29f716379a07daaed285ee5bc880b1e455755ee5 Mon Sep 17 00:00:00 2001 From: Arunim Samudra Date: Fri, 24 Jan 2020 19:03:14 +0530 Subject: [PATCH 1/2] Changed the documentation path from doc/source/api.rst to doc/source/reference --- doc/source/development/contributing.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst index 9599dc5bd1412..46fd9d1157278 100644 --- a/doc/source/development/contributing.rst +++ b/doc/source/development/contributing.rst @@ -410,7 +410,7 @@ Some other important things to know about the docs: doc build. This approach means that code examples will always be up to date, but it does make the doc building a bit more complex. -* Our API documentation in ``doc/source/api.rst`` houses the auto-generated +* Our API documentation files in ``doc/source/reference`` houses the auto-generated documentation from the docstrings. For classes, there are a few subtleties around controlling which methods and attributes have pages auto-generated. @@ -428,7 +428,8 @@ Some other important things to know about the docs: ``Methods`` section in the class docstring. See ``CategoricalIndex`` for an example. - Every method should be included in a ``toctree`` in ``api.rst``, else Sphinx + Every method should be included in a ``toctree`` in one of the documentation files in + ``doc/source/reference``, else Sphinx will emit a warning. .. note:: @@ -444,11 +445,11 @@ Some other important things to know about the docs: The utility script ``scripts/validate_docstrings.py`` can be used to get a csv summary of the API documentation. And also validate common errors in the docstring of a specific class, function or method. The summary also compares the list of -methods documented in ``doc/source/api.rst`` (which is used to generate +methods documented in the files in ``doc/source/reference`` (which is used to generate the `API Reference `_ page) and the actual public methods. -This will identify methods documented in ``doc/source/api.rst`` that are not actually -class methods, and existing methods that are not documented in ``doc/source/api.rst``. +This will identify methods documented in ``doc/source/reference`` that are not actually +class methods, and existing methods that are not documented in ``doc/source/reference``. Updating a *pandas* docstring From 87c6373f6163999f13444027a6fb4cdde3e54a21 Mon Sep 17 00:00:00 2001 From: Arunim Samudra Date: Fri, 24 Jan 2020 19:11:49 +0530 Subject: [PATCH 2/2] Changed the path from doc/source/api.rst to doc/source/reference --- doc/source/development/contributing.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/development/contributing.rst b/doc/source/development/contributing.rst index 46fd9d1157278..a9237c239701b 100644 --- a/doc/source/development/contributing.rst +++ b/doc/source/development/contributing.rst @@ -410,7 +410,7 @@ Some other important things to know about the docs: doc build. This approach means that code examples will always be up to date, but it does make the doc building a bit more complex. -* Our API documentation files in ``doc/source/reference`` houses the auto-generated +* Our API documentation files in ``doc/source/reference`` house the auto-generated documentation from the docstrings. For classes, there are a few subtleties around controlling which methods and attributes have pages auto-generated.