DOC: Change release and whatsnew (#21599)

* DOC: Change release and whatsnew

Changes:

* We will include the correct (latest on master or maintenance branch)
  whatsnew directly in the index.rst toctree
* Contributors are included in the whatsnew for each version (automatically)
* Removed release.rst
* Added new releases.rst which has toctrees for each release

Incidental changes

* Updated style.ipynb. Writing the jinja template was confusing sphinx. We
  included it in the git source now.
* Fixing some inconsitent header levels (will do more)
* Refactored announce.py to support auto-generated contributors

.gitignore

@@ -109,6 +109,5 @@ doc/build/html/index.html
 # Windows specific leftover:
 doc/tmp.sv
 doc/source/styled.xlsx
-doc/source/templates/
 env/
 doc/source/savefig/

ci/build_docs.sh

@@ -5,7 +5,7 @@ if [ "${TRAVIS_OS_NAME}" != "linux" ]; then
    exit 0
 fi
 
-cd "$TRAVIS_BUILD_DIR"
+cd "$TRAVIS_BUILD_DIR"/doc
 echo "inside $0"
 
 if [ "$DOC" ]; then
@@ -14,10 +14,6 @@ if [ "$DOC" ]; then
 
     source activate pandas
 
-    mv "$TRAVIS_BUILD_DIR"/doc /tmp
-    mv "$TRAVIS_BUILD_DIR/LICENSE" /tmp  # included in the docs.
-    cd /tmp/doc
-
     echo ###############################
     echo # Log file for the doc build  #
     echo ###############################
@@ -29,7 +25,7 @@ if [ "$DOC" ]; then
     echo # Create and send docs #
     echo ########################
 
-    cd /tmp/doc/build/html
+    cd build/html
     git config --global user.email "pandas-docs-bot@localhost.foo"
     git config --global user.name "pandas-docs-bot"
 

ci/deps/travis-36-doc.yaml

@@ -8,6 +8,7 @@ dependencies:
   - bottleneck
   - cython>=0.28.2
   - fastparquet
+  - gitpython
   - html5lib
   - hypothesis>=3.58.0
   - ipykernel

doc/make.py

@@ -126,7 +126,12 @@ def _process_single_doc(self, single_doc):
             self.single_doc = 'api'
         elif os.path.exists(os.path.join(SOURCE_PATH, single_doc)):
             self.single_doc_type = 'rst'
-            self.single_doc = os.path.splitext(os.path.basename(single_doc))[0]
+
+            if 'whatsnew' in single_doc:
+                basename = single_doc
+            else:
+                basename = os.path.basename(single_doc)
+            self.single_doc = os.path.splitext(basename)[0]
         elif os.path.exists(
                 os.path.join(SOURCE_PATH, '{}.rst'.format(single_doc))):
             self.single_doc_type = 'rst'

doc/source/conf.py

@@ -40,7 +40,6 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.append(os.path.abspath('.'))
 sys.path.insert(0, os.path.abspath('../sphinxext'))
-
 sys.path.extend([
 
     # numpy standard doc extensions
@@ -75,6 +74,7 @@
               'sphinx.ext.ifconfig',
               'sphinx.ext.linkcode',
               'nbsphinx',
+              'contributors',  # custom pandas extension
               ]
 
 try:
@@ -120,7 +120,9 @@
 templates_path = ['../_templates']
 
 # The suffix of source filenames.
-source_suffix = '.rst'
+source_suffix = [
+    '.rst',
+]
 
 # The encoding of source files.
 source_encoding = 'utf-8'
@@ -298,8 +300,26 @@
     for page in moved_api_pages
 }
 
+
+common_imports = """\
+.. currentmodule:: pandas
+
+.. ipython:: python
+   :suppress:
+
+   import numpy as np
+   from pandas import *
+   import pandas as pd
+   randn = np.random.randn
+   np.set_printoptions(precision=4, suppress=True)
+   options.display.max_rows = 15
+   from pandas.compat import StringIO
+"""
+
+
 html_context = {
-    'redirects': {old: new for old, new in moved_api_pages}
+    'redirects': {old: new for old, new in moved_api_pages},
+    'common_imports': common_imports,
 }
 
 # If false, no module index is generated.
@@ -654,7 +674,23 @@ def process_class_docstrings(app, what, name, obj, options, lines):
 ]
 
 
+def rstjinja(app, docname, source):
+    """
+    Render our pages as a jinja template for fancy templating goodness.
+    """
+    # http://ericholscher.com/blog/2016/jul/25/integrating-jinja-rst-sphinx/
+    # Make sure we're outputting HTML
+    if app.builder.format != 'html':
+        return
+    src = source[0]
+    rendered = app.builder.templates.render_string(
+        src, app.config.html_context
+    )
+    source[0] = rendered
+
+
 def setup(app):
+    app.connect("source-read", rstjinja)
     app.connect("autodoc-process-docstring", remove_flags_docstring)
     app.connect("autodoc-process-docstring", process_class_docstrings)
     app.add_autodocumenter(AccessorDocumenter)

doc/source/contributing.rst

@@ -1103,7 +1103,7 @@ Information on how to write a benchmark and how to use asv can be found in the
 Documenting your code
 ---------------------
 
-Changes should be reflected in the release notes located in ``doc/source/whatsnew/vx.y.z.txt``.
+Changes should be reflected in the release notes located in ``doc/source/whatsnew/vx.y.z.rst``.
 This file contains an ongoing change log for each release.  Add an entry to this file to
 document your fix, enhancement or (unavoidable) breaking change.  Make sure to include the
 GitHub issue number when adding your entry (using ``:issue:`1234``` where ``1234`` is the

doc/source/index.rst.template

@@ -118,7 +118,7 @@ See the package overview for more detail about what's in the library.
     {{ single_doc }}
     {% endif -%}
     {% if not single_doc -%}
-    whatsnew
+    What's New <whatsnew/v0.24.0>
     install
     contributing
     overview
@@ -159,5 +159,5 @@ See the package overview for more detail about what's in the library.
     developer
     internals
     extending
-    release
+    releases
     {% endif -%}

doc/source/releases.rst

@@ -0,0 +1,203 @@
+.. _release:
+
+*************
+Release Notes
+*************
+
+This is the list of changes to pandas between each release. For full details,
+see the commit logs at http://github.com/pandas-dev/pandas. For install and
+upgrade instructions, see :ref:`install`.
+
+Version 0.24
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.24.0
+
+Version 0.23
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.23.4
+   whatsnew/v0.23.3
+   whatsnew/v0.23.2
+   whatsnew/v0.23.1
+   whatsnew/v0.23.0
+
+Version 0.22
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.22.0
+
+Version 0.21
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.21.0
+   whatsnew/v0.21.1
+
+Version 0.20
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.20.0
+   whatsnew/v0.20.2
+   whatsnew/v0.20.3
+
+Version 0.19
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.19.0
+   whatsnew/v0.19.1
+   whatsnew/v0.19.2
+
+Version 0.18
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.18.0
+   whatsnew/v0.18.1
+
+Version 0.17
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.17.0
+   whatsnew/v0.17.1
+
+Version 0.16
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.16.0
+   whatsnew/v0.16.1
+   whatsnew/v0.16.2
+
+Version 0.15
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.15.0
+   whatsnew/v0.15.1
+   whatsnew/v0.15.2
+
+Version 0.14
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.14.0
+   whatsnew/v0.14.1
+
+Version 0.13
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.13.0
+   whatsnew/v0.13.1
+
+Version 0.12
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.12.0
+
+Version 0.11
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.11.0
+
+Version 0.10
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.10.0
+   whatsnew/v0.10.1
+
+Version 0.9
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.9.0
+   whatsnew/v0.9.1
+
+Version 0.8
+------------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.8.0
+   whatsnew/v0.8.1
+
+Version 0.7
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.7.0
+   whatsnew/v0.7.1
+   whatsnew/v0.7.2
+   whatsnew/v0.7.3
+
+Version 0.6
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+
+   whatsnew/v0.6.0
+   whatsnew/v0.6.1
+
+Version 0.5
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+
+   whatsnew/v0.5.0
+
+Version 0.4
+-----------
+
+.. toctree::
+   :maxdepth: 2
+
+   whatsnew/v0.4.x