Merge pull request #6441 from jorisvandenbossche/doc-sphinxext-readme

DOC: add explanation to doc/sphinxext

Author: jorisvandenbossche

doc/source/conf.py

@@ -40,8 +40,8 @@
               'sphinx.ext.extlinks',
               'sphinx.ext.todo',
               'numpydoc', # used to parse numpy-style docstrings for autodoc
-              'ipython_directive',
-              'ipython_console_highlighting',
+              'ipython_sphinxext.ipython_directive',
+              'ipython_sphinxext.ipython_console_highlighting',
               'sphinx.ext.intersphinx',
               'sphinx.ext.todo',
               'sphinx.ext.coverage',

doc/sphinxext/README.rst

@@ -0,0 +1,17 @@
+sphinxext
+=========
+
+This directory contains copies of different sphinx extensions in use in the
+pandas documentation. These copies originate from other projects:
+
+- ``numpydoc`` - Numpy's Sphinx extensions: this can be found at its own
+  repository: https://github.com/numpy/numpydoc
+- ``ipython_directive`` and ``ipython_console_highlighting`` in the folder
+  `ipython_sphinxext` - Sphinx extensions from IPython: these are included
+  in IPython: https://github.com/ipython/ipython/tree/master/IPython/sphinxext
+
+.. note::
+
+    These copies are maintained at the respective projects, so fixes should,
+    to the extent possible, be pushed upstream instead of only adapting our
+    local copy to avoid divergence between the the local and upstream version.