diff --git a/doc/make.py b/doc/make.py index 0b14a9dcd4c342..eb4a33a569c5af 100755 --- 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( + '', + 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 = ''' + + + + + +

+ The page has been moved to {title} +

+ + + ''' + 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 new file mode 100644 index 00000000000000..4f4b3d7fc07809 --- /dev/null +++ b/doc/redirects.csv @@ -0,0 +1,37 @@ +# This file should contain all the redirects in the documentation +# in the format `,` + +# 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