From c5d3e9e8609faf048c8c890df99c20df30bb6350 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Thu, 10 Jan 2019 23:34:22 +0000 Subject: [PATCH 1/4] DOC: Implementing redirect system, and adding user_guide redirects --- doc/make.py | 74 ++++++++++++++++++++++++++++++++++++++++++++++- doc/redirects.csv | 23 +++++++++++++++ 2 files changed, 96 insertions(+), 1 deletion(-) create mode 100644 doc/redirects.csv diff --git a/doc/make.py b/doc/make.py index 0b14a9dcd4c34..294351ab68c91 100755 --- a/doc/make.py +++ b/doc/make.py @@ -15,15 +15,19 @@ 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') +BASE_REDIRECT_URL = 'https://pandas.pydata.org/pandas-docs/stable/' class DocBuilder: @@ -139,6 +143,72 @@ 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' + + with open(path, 'w') as redirects_fd: + redirects_fd.write(html.format( + url='{}{}.html'.format(BASE_REDIRECT_URL, row[1]), + title=title)) + def html(self): """ Build HTML documentation. @@ -150,6 +220,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 0000000000000..c0899ca81169c --- /dev/null +++ b/doc/redirects.csv @@ -0,0 +1,23 @@ +# This file should contain all the redirects in the documentation +# in the format `,` + +# 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 From 6707da63ad13f2a2e4c7f4856262d00d19646949 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Tue, 15 Jan 2019 01:24:19 +0000 Subject: [PATCH 2/4] Using relative urls for the redirect --- doc/make.py | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/make.py b/doc/make.py index 294351ab68c91..ae1c6935935a8 100755 --- a/doc/make.py +++ b/doc/make.py @@ -27,7 +27,6 @@ SOURCE_PATH = os.path.join(DOC_PATH, 'source') BUILD_PATH = os.path.join(DOC_PATH, 'build') REDIRECTS_FILE = os.path.join(DOC_PATH, 'redirects.csv') -BASE_REDIRECT_URL = 'https://pandas.pydata.org/pandas-docs/stable/' class DocBuilder: @@ -204,10 +203,10 @@ def _add_redirects(self): # sphinx specific stuff title = 'this page' - with open(path, 'w') as redirects_fd: - redirects_fd.write(html.format( - url='{}{}.html'.format(BASE_REDIRECT_URL, row[1]), - title=title)) + with open(path, 'w') as moved_page_fd: + moved_page_fd.write( + html.format(url='{}.html'.format(row[1]), + title=title)) def html(self): """ From c43fc560c3965beac8dee74558ceffbc2acc19ce Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Tue, 15 Jan 2019 20:25:36 +0000 Subject: [PATCH 3/4] Validating that no file is overwritten by a redirect --- doc/make.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/doc/make.py b/doc/make.py index ae1c6935935a8..eb4a33a569c5a 100755 --- a/doc/make.py +++ b/doc/make.py @@ -203,6 +203,11 @@ def _add_redirects(self): # 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]), From 3ae3726c97067aed1b963cee57c31be996da1b87 Mon Sep 17 00:00:00 2001 From: Marc Garcia Date: Wed, 23 Jan 2019 15:52:09 +0000 Subject: [PATCH 4/4] Adding redirects for getting started and development sections --- doc/redirects.csv | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/redirects.csv b/doc/redirects.csv index c0899ca81169c..4f4b3d7fc0780 100644 --- a/doc/redirects.csv +++ b/doc/redirects.csv @@ -1,6 +1,13 @@ # 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 @@ -21,3 +28,10 @@ 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