DOC: Implementing redirect system, and adding user_guide redirects (#24715)

datapythonista · TomAugspurger · commit 6a745d826d9d · 2019-01-23T12:30:34.000-06:00
* DOC: Implementing redirect system, and adding user_guide redirects

* Using relative urls for the redirect

* Validating that no file is overwritten by a redirect

* Adding redirects for getting started and development sections
diff --git a/doc/make.py b/doc/make.py
@@ -15,15 +15,18 @@
 import sys
 import os
 import shutil
+import csv
 import subprocess
 import argparse
 import webbrowser
+import docutils
+import docutils.parsers.rst
 
 
 DOC_PATH = os.path.dirname(os.path.abspath(__file__))
 SOURCE_PATH = os.path.join(DOC_PATH, 'source')
 BUILD_PATH = os.path.join(DOC_PATH, 'build')
-BUILD_DIRS = ['doctrees', 'html', 'latex', 'plots', '_static', '_templates']
+REDIRECTS_FILE = os.path.join(DOC_PATH, 'redirects.csv')
 
 
 class DocBuilder:
@@ -139,6 +142,77 @@ def _open_browser(self, single_doc_html):
                            single_doc_html)
         webbrowser.open(url, new=2)
 
+    def _get_page_title(self, page):
+        """
+        Open the rst file `page` and extract its title.
+        """
+        fname = os.path.join(SOURCE_PATH, '{}.rst'.format(page))
+        option_parser = docutils.frontend.OptionParser(
+            components=(docutils.parsers.rst.Parser,))
+        doc = docutils.utils.new_document(
+            '<doc>',
+            option_parser.get_default_values())
+        with open(fname) as f:
+            data = f.read()
+
+        parser = docutils.parsers.rst.Parser()
+        # do not generate any warning when parsing the rst
+        with open(os.devnull, 'a') as f:
+            doc.reporter.stream = f
+            parser.parse(data, doc)
+
+        section = next(node for node in doc.children
+                       if isinstance(node, docutils.nodes.section))
+        title = next(node for node in section.children
+                     if isinstance(node, docutils.nodes.title))
+
+        return title.astext()
+
+    def _add_redirects(self):
+        """
+        Create in the build directory an html file with a redirect,
+        for every row in REDIRECTS_FILE.
+        """
+        html = '''
+        <html>
+            <head>
+                <meta http-equiv="refresh" content="0;URL={url}"/>
+            </head>
+            <body>
+                <p>
+                    The page has been moved to <a href="{url}">{title}</a>
+                </p>
+            </body>
+        <html>
+        '''
+        with open(REDIRECTS_FILE) as mapping_fd:
+            reader = csv.reader(mapping_fd)
+            for row in reader:
+                if not row or row[0].strip().startswith('#'):
+                    continue
+
+                path = os.path.join(BUILD_PATH,
+                                    'html',
+                                    *row[0].split('/')) + '.html'
+
+                try:
+                    title = self._get_page_title(row[1])
+                except Exception:
+                    # the file can be an ipynb and not an rst, or docutils
+                    # may not be able to read the rst because it has some
+                    # sphinx specific stuff
+                    title = 'this page'
+
+                if os.path.exists(path):
+                    raise RuntimeError((
+                        'Redirection would overwrite an existing file: '
+                        '{}').format(path))
+
+                with open(path, 'w') as moved_page_fd:
+                    moved_page_fd.write(
+                        html.format(url='{}.html'.format(row[1]),
+                                    title=title))
+
     def html(self):
         """
         Build HTML documentation.
@@ -150,6 +224,8 @@ def html(self):
 
         if self.single_doc_html is not None:
             self._open_browser(self.single_doc_html)
+        else:
+            self._add_redirects()
         return ret_code
 
     def latex(self, force=False):
diff --git a/doc/redirects.csv b/doc/redirects.csv
@@ -0,0 +1,37 @@
+# This file should contain all the redirects in the documentation
+# in the format `<old_path>,<new_path>`
+
+# getting started
+10min,getting_started/10min
+basics,getting_started/basics
+dsintro,getting_started/dsintro
+overview,getting_started/overview
+tutorials,getting_started/tutorials
+
+# user guide
+advanced,user_guide/advanced
+categorical,user_guide/categorical
+computation,user_guide/computation
+enhancingperf,user_guide/enhancingperf
+gotchas,user_guide/gotchas
+groupby,user_guide/groupby
+indexing,user_guide/indexing
+integer_na,user_guide/integer_na
+io,user_guide/io
+merging,user_guide/merging
+missing_data,user_guide/missing_data
+options,user_guide/options
+reshaping,user_guide/reshaping
+sparse,user_guide/sparse
+style,user_guide/style
+text,user_guide/text
+timedeltas,user_guide/timedeltas
+timeseries,user_guide/timeseries
+visualization,user_guide/visualization
+
+# development
+contributing,development/contributing
+contributing_docstring,development/contributing_docstring
+developer,development/developer
+extending,development/extending
+internals,development/internals
