Share code for Sphinx make.py and conf.py across all repos

sphinx/make.py

@@ -1,19 +1,32 @@
 #!/usr/bin/env python3
+"""
+Sphinx documentation build script
+"""
+
 import os
-import sys
-from typing import Callable, NamedTuple, Tuple
 import shutil
 import subprocess
+import sys
+from typing import *
 
-pwd = os.path.realpath(os.path.dirname(__file__))
+cwd = os.getcwd()
 
 # define Sphinx-commands:
 CMD_SPHINXBUILD = "sphinx-build"
 CMD_SPHINXAPIDOC = "sphinx-apidoc"
 
 # define directories:
-SOURCEDIR = os.path.join(pwd, "source")
-BUILDDIR = os.path.join(pwd, "build")
+# todo: check which ones are eventually obsolete
+SKLEARNDF_SOURCEDIR = os.path.join(cwd, os.pardir, "src")
+SOURCEDIR = os.path.join(cwd, "source")
+AUXILIARYDIR = os.path.join(cwd, "auxiliary")
+SOURCEAPIDIR = os.path.join(SOURCEDIR, "api")
+BUILDDIR = os.path.join(cwd, "build")
+TEMPLATEDIR = os.path.join(SOURCEDIR, "_templates")
+SCRIPTSDIR = os.path.join(SOURCEDIR, "scripts")
+TUTORIALDIR = os.path.join(SOURCEDIR, "tutorial")
+NOTEBOOKDIR = os.path.join(SKLEARNDF_SOURCEDIR, os.pardir, "notebooks")
+TUTORIALBUILD = os.path.join(SCRIPTSDIR, "transform_notebook.py")
 
 
 class MakeCommand(NamedTuple):
@@ -26,26 +39,56 @@ class MakeCommand(NamedTuple):
 
 
 # Define Python target callables:
-def fun_clean():
-    """ Cleans the Sphinx build directory. """
+def fun_clean() -> None:
+    """
+    Clean the Sphinx build directory.
+    """
     print_running_command(cmd=clean)
     if os.path.exists(BUILDDIR):
-        shutil.rmtree(path=BUILDDIR,)
+        shutil.rmtree(path=BUILDDIR)
+
+
+def fun_apidoc() -> None:
+    """
+    Run Sphinx apidoc.
+    """
+    print_running_command(cmd=apidoc)
+    sphinxapidocopts = [
+        "-e",
+        f"-t {quote_path(TEMPLATEDIR)}",
+        "--no-toc",
+        f"-o {quote_path(SOURCEAPIDIR)}",
+        "-f",
+        quote_path(SKLEARNDF_SOURCEDIR),
+    ]
+    os.environ["SPHINX_APIDOC_OPTIONS"] = ",".join(["members", "undoc-members"])
+    subprocess.run(
+        args=f"{CMD_SPHINXAPIDOC} {' '.join(sphinxapidocopts)}", shell=True, check=True
+    )
+
 
+def fun_html() -> None:
+    """
+    Run a Sphinx build for generating HTML.
+    """
 
-def fun_html():
-    """ Runs a Sphinx build for pytools generating HTML. """
     print_running_command(cmd=html)
     os.makedirs(BUILDDIR, exist_ok=True)
-    sphinx_html_opts = [
-        "-M html",
-        quote_path(SOURCEDIR),
-        quote_path(BUILDDIR),
-    ]
+    sphinx_html_opts = ["-M html", quote_path(SOURCEDIR), quote_path(BUILDDIR)]
     subprocess.run(
         args=f"{CMD_SPHINXBUILD} {' '.join(sphinx_html_opts)}", shell=True, check=True
     )
 
+    # create interactive versions of all notebooks
+
+    sys.path.append(os.path.abspath(os.path.dirname(__file__)))
+    # noinspection PyUnresolvedReferences
+    from source.scripts.transform_notebook import docs_notebooks_to_interactive
+
+    for notebook_source_dir in [TUTORIALDIR, AUXILIARYDIR]:
+        if os.path.isdir(notebook_source_dir):
+            docs_notebooks_to_interactive(notebook_source_dir, NOTEBOOKDIR)
+
 
 # Define MakeCommands
 clean = MakeCommand(
@@ -54,18 +97,26 @@ def fun_html():
     python_target=fun_clean,
     depends_on=(),
 )
+apidoc = MakeCommand(
+    command="apidoc",
+    description="generate Sphinx apidoc from sources.",
+    python_target=fun_apidoc,
+    depends_on=(clean,),
+)
 html = MakeCommand(
     command="html",
-    description="build pytools Sphinx docs as HTML",
+    description="build Sphinx docs as HTML",
     python_target=fun_html,
     depends_on=(clean,),
 )
 
-available_cmds = (clean, html)
+available_cmds = (clean, apidoc, html)
 
 
-def run_make():
-    """ Run this make script with the given arguments. """
+def run_make() -> None:
+    """
+    Run this make script with the given arguments.
+    """
     if len(sys.argv) < 2:
         print_usage()
 
@@ -100,15 +151,17 @@ def quote_path(path: str) -> str:
 
 
 def print_usage() -> None:
-    # Define a help string to explain the usage:
-    usage = """
-    pytools docs build script
-    =========================
-
-    Available program arguments:
     """
+    Print a help string to explain the usage of this script.
+    """
+    usage = """Sphinx documentation build script
+=================================
+
+Available program arguments:
+"""
 
     usage += "\n".join([f"\t{c.command} – {c.description}" for c in available_cmds])
+
     print(usage)
 
 

sphinx/source/_static_base/css/gamma.css

@@ -0,0 +1,9 @@
+code {
+    color: #295e7e;
+}
+
+.py.class {
+    margin-top: 32pt;
+    padding-top: 32pt;
+    border-top: 2pt solid #295e7e;
+}

sphinx/source/_static_base/js/gamma.js

@@ -0,0 +1,3 @@
+$(document).ready(function(){
+  $('a.reference.external').attr('target', '_blank');
+});

sphinx/source/conf.py

@@ -1,165 +1,28 @@
 """
 Configuration file for the Sphinx documentation builder.
 
-For a full list of options see the documentation:
-https://www.sphinx-doc.org/en/master/usage/configuration.html
+Receives majority of configuration from pytools conf_base.py
 """
 
-# -- Path setup --------------------------------------------------------------
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-#
-
-import logging
+import os
 import sys
 
-from sphinx.application import Sphinx
-
-log = logging.getLogger(name=__name__)
-log.setLevel(logging.INFO)
-
-
-# If extensions (or modules to document with autodoc) are in another directory,
-# add these directories to sys.path here. If the directory is relative to the
-# documentation root, use os.path.abspath to make it absolute, like shown here.
-
-# noinspection DuplicatedCode
-def _set_paths() -> None:
-    import sys
-    import os
-
-    module_paths = ["pytools"]
-
-    if "cwd" not in globals():
-        # noinspection PyGlobalUndefined
-        global cwd
-        cwd = os.path.join(os.getcwd(), os.pardir, os.pardir)
-    print(f"working dir is '{os.getcwd()}'")
-    for module_path in module_paths:
-        if module_path not in sys.path:
-            # noinspection PyUnboundLocalVariable
-            sys.path.insert(0, os.path.abspath(f"{cwd}/{os.pardir}/{module_path}/src"))
-            print(f"added `{sys.path[0]}` to python paths")
-
-
-_set_paths()
-
-log.info(f"sys.path = {sys.path}")
-
-# -- Project information -----------------------------------------------------
-
-project = "pytools"
-copyright = "2020, The Boston Consulting Group (BCG)"
-author = "FACET Team"
-
-# -- General configuration ---------------------------------------------------
-
-# Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
-# ones.
-extensions = [
-    "nbsphinx",
-    "sphinx.ext.autodoc",
-    "sphinx.ext.imgmath",
-    "sphinx.ext.intersphinx",
-    "sphinx.ext.viewcode",
-    "sphinx_autodoc_typehints",
-]
-
-# -- Options for autodoc / autosummary -------------------------------------------------
-
-# generate autosummary even if no references
-autosummary_generate = True
-
-# always overwrite generated auto summaries with newly generated versions
-autosummary_generate_overwrite = True
-
-autodoc_default_options = {
-    "no-ignore-module-all": True,
-    "inherited-members": True,
-    "imported-members": True,
-    "no-show-inheritance": True,
-    "member-order": "groupwise",
-}
-
-nbsphinx_allow_errors = True
-nbsphinx_timeout = 60 * 15  # 15 minutes due to tutorial/model notebook
-
-# add intersphinx mapping
-intersphinx_mapping = {
-    "pandas": ("https://pandas.pydata.org/pandas-docs/stable", None),
-    "matplotlib": ("https://matplotlib.org", None),
-    "numpy": ("https://numpy.org/doc/stable", None),
-    "python": ("https://docs.python.org/3.6", None),
-    "scipy": ("https://docs.scipy.org/doc/scipy/reference", None),
-    "sklearn": ("https://scikit-learn.org/stable", None),
-    "joblib": ("https://joblib.readthedocs.io/en/latest", None),
-    "sphinx": ("https://www.sphinx-doc.org/en/master", None),
-}
-
-intersphinx_collapsible_submodules = {
-    "pandas.core.frame": "pandas",
-    "pandas.core.series": "pandas",
-    "pandas.core.panel": "pandas",
-    "pandas.core.indexes.base": "pandas",
-    "pandas.core.indexes.multi": "pandas",
-}
-
-# Add any paths that contain templates here, relative to this directory.
-templates_path = ["_templates"]
-
-source_suffix = [".rst", ".md", ".ipynb"]
-
-# List of patterns, relative to source directory, that match files and
-# directories to ignore when looking for source files.
-# This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["*/.ipynb_checkpoints/*"]
-
-# -- Options for sphinx_autodoc_typehints ----------------------------------------------
-set_type_checking_flag = False
-typehints_fully_qualified = False
-always_document_param_types = False
-
-# -- Options for Math output -----------------------------------------------------------
-
-imgmath_image_format = "svg"
-imgmath_use_preview = True
-
-# -- Options for HTML output -------------------------------------------------
-
-# The theme to use for HTML and HTML Help pages.  See the documentation for
-# a list of builtin themes.
-#
-html_theme = "pydata_sphinx_theme"
-
-# Add any paths that contain custom static files (such as style sheets) here,
-# relative to this directory. They are copied after the builtin static files,
-# so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ["_static"]
-html_logo = "_static/gamma_logo.jpg"
-latex_logo = html_logo
-
-# Class documentation to include docstrings both global to the class, and from __init__
-autoclass_content = "both"
-
-
-# -- End of options section ------------------------------------------------------------
-
-
-def setup(app: Sphinx) -> None:
-    """
-    Add event handlers to the Sphinx application object
-    :param app: the Sphinx application object
-    """
+sys.path.append(
+    os.path.abspath(
+        os.path.join(
+            os.path.dirname(__file__),
+            os.pardir,
+            os.pardir,
+            os.pardir,
+            "pytools",
+            "sphinx",
+            "source",
+        )
+    )
+)
 
-    from pytools.sphinx import AddInheritance, CollapseModulePaths
+from conf_base import *
 
-    AddInheritance(collapsible_submodules=intersphinx_collapsible_submodules).connect(
-        app=app
-    )
+# ----- custom configuration -----
 
-    CollapseModulePaths(
-        collapsible_submodules=intersphinx_collapsible_submodules
-    ).connect(app=app, priority=100000)
+set_config(project="pytools", modules=["pytools"])