Merge pull request #6179 from y-p/PR_fast_docs

BLD/DOC: Speed up doc building via jinja2 and conf.py logic

Author: y-p

.gitignore

@@ -19,6 +19,7 @@ doc/source/generated
 doc/source/_static
 doc/source/vbench
 doc/source/vbench.rst
+doc/source/index.rst
 doc/build/html/index.html
 *flymake*
 scikits

doc/make.py

@@ -21,6 +21,8 @@
 import shutil
 import sys
 import sphinx
+import argparse
+import jinja2
 
 os.environ['PYTHONPATH'] = '..'
 
@@ -77,7 +79,7 @@ def build_pandas():
         os.system('python setup.py clean')
         os.system('python setup.py build_ext --inplace')
         os.chdir('doc')
-        
+
 def build_prev(ver):
     if os.system('git checkout v%s' % ver) != 1:
         os.chdir('..')
@@ -267,22 +269,77 @@ def _get_config():
 # current_dir = os.getcwd()
 # os.chdir(os.path.dirname(os.path.join(current_dir, __file__)))
 
-if len(sys.argv) > 2:
-    ftype = sys.argv[1]
-    ver = sys.argv[2]
-
-    if ftype == 'build_previous':
-        build_prev(ver)
-    if ftype == 'upload_previous':
-        upload_prev(ver)
-elif len(sys.argv) > 1:
-    for arg in sys.argv[1:]:
-        func = funcd.get(arg)
-        if func is None:
-            raise SystemExit('Do not know how to handle %s; valid args are %s' % (
-                arg, list(funcd.keys())))
-        func()
-else:
-    small_docs = False
-    all()
+import argparse
+argparser = argparse.ArgumentParser(description="""
+Pandas documentation builder
+""".strip())
+
+# argparser.add_argument('-arg_name', '--arg_name',
+#                    metavar='label for arg help',
+#                    type=str|etc,
+#                    nargs='N|*|?|+|argparse.REMAINDER',
+#                    required=False,
+#                    #choices='abc',
+#                    help='help string',
+#                    action='store|store_true')
+
+# args = argparser.parse_args()
+
+#print args.accumulate(args.integers)
+
+def generate_index(api=True, single=False, **kwds):
+    from jinja2 import Template
+    with open("source/index.rst.template") as f:
+        t = Template(f.read())
+
+    with open("source/index.rst","wb") as f:
+        f.write(t.render(api=api,single=single,**kwds))
+
+import argparse
+argparser = argparse.ArgumentParser(description="Pandas documentation builder",
+                                    epilog="Targets : %s" % funcd.keys())
+
+argparser.add_argument('--no-api',
+                   default=False,
+                   help='Ommit api and autosummary',
+                   action='store_true')
+argparser.add_argument('--single',
+                   metavar='FILENAME',
+                   type=str,
+                   default=False,
+                   help='filename of section to compile, e.g. "indexing"')
+
+def main():
+    args, unknown = argparser.parse_known_args()
+    sys.argv = [sys.argv[0]] + unknown
+    if args.single:
+        args.single = os.path.basename(args.single).split(".rst")[0]
+
+    if 'clean' in unknown:
+        args.single=False
+
+    generate_index(api=not args.no_api and not args.single, single=args.single)
+
+    if len(sys.argv) > 2:
+        ftype = sys.argv[1]
+        ver = sys.argv[2]
+
+        if ftype == 'build_previous':
+            build_prev(ver)
+        if ftype == 'upload_previous':
+            upload_prev(ver)
+    elif len(sys.argv) == 2:
+        for arg in sys.argv[1:]:
+            func = funcd.get(arg)
+            if func is None:
+                raise SystemExit('Do not know how to handle %s; valid args are %s' % (
+                    arg, list(funcd.keys())))
+            func()
+    else:
+        small_docs = False
+        all()
 # os.chdir(current_dir)
+
+if __name__ == '__main__':
+    import sys
+    sys.exit(main())

doc/source/conf.py

@@ -12,6 +12,7 @@
 
 import sys
 import os
+import re
 from pandas.compat import u
 
 # If extensions (or modules to document with autodoc) are in another directory,
@@ -46,11 +47,50 @@
               'sphinx.ext.coverage',
               'sphinx.ext.pngmath',
               'sphinx.ext.ifconfig',
-              'sphinx.ext.autosummary',
               'matplotlib.sphinxext.only_directives',
               'matplotlib.sphinxext.plot_directive',
               ]
 
+
+
+with open("index.rst") as f:
+    lines = f.readlines()
+
+# only include the slow autosummary feature if we're building the API section
+# of the docs
+
+# JP: added from sphinxdocs
+autosummary_generate = False
+
+if any([re.match("\s*api\s*",l) for l in lines]):
+    extensions.append('sphinx.ext.autosummary')
+    autosummary_generate = True
+
+ds = []
+for f in os.listdir(os.path.dirname(__file__)):
+    if (not f.endswith(('.rst'))) or (f.startswith('.')) or os.path.basename(f) == 'index.rst':
+        continue
+
+    _f = f.split('.rst')[0]
+    if not any([re.match("\s*%s\s*$" % _f,l) for l in lines]):
+        ds.append(f)
+
+if ds:
+    print("I'm about to DELETE the following:\n%s\n" % list(sorted(ds)))
+    sys.stdout.write("WARNING: I'd like to delete those to speed up proccesing (yes/no)? ")
+    answer = raw_input()
+
+    if answer.lower().strip() in ('y','yes'):
+        for f in ds:
+            f = os.path.join(os.path.join(os.path.dirname(__file__),f))
+            f= os.path.abspath(f)
+            try:
+                print("Deleting %s" % f)
+                os.unlink(f)
+            except:
+                print("Error deleting %s" % f)
+                pass
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['../_templates']
 
@@ -80,9 +120,6 @@
 # The full version, including alpha/beta/rc tags.
 release = version
 
-# JP: added from sphinxdocs
-autosummary_generate = True
-
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
 # language = None

doc/source/index.rst renamed to doc/source/index.rst.template

@@ -109,6 +109,10 @@ See the package overview for more detail about what's in the library.
 .. toctree::
     :maxdepth: 3
 
+    {% if single -%}
+    {{ single }}
+    {% endif -%}
+    {%if not single -%}
     whatsnew
     install
     faq
@@ -136,6 +140,11 @@ See the package overview for more detail about what's in the library.
     ecosystem
     comparison_with_r
     comparison_with_sql
+    {% endif -%}
+    {% if api -%}
     api
+    {% endif -%}
+    {%if not single -%}
     contributing
     release
+    {% endif -%}