Thorough scouring of docs + doc build infrastructure (#135)

* streamline & update CI * remove extra space - flake8 complaining * break out classify tests * spruce up warning & docstrings [1] * add back and reword comment * clean up pooling * doc work [1 of n] * doc work [2 of n] * doc work [3 of n] * remove spaces after table string * doc work continued * polishing up pooling, _api * doc work continues... * clean more classes * final(?) docstring polish up * add linting to CI * correct syntax
pysal · Nov 18, 2022 · 971a3ea · 971a3ea
1 parent bd11fd0
commit 971a3ea
Show file tree

Hide file tree

Showing 26 changed files with 2,297 additions and 6,318 deletions.
diff --git a/.github/workflows/testing.yml b/.github/workflows/testing.yml
@@ -11,7 +11,14 @@ on:
     - cron: "59 21 * * *"
 
 jobs:
+  linting:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v4
+      - uses: pre-commit/[email protected]
   testing:
+    needs: linting
     name: (${{ matrix.os }}, ${{ matrix.environment-file }})
     runs-on: ${{ matrix.os }}
     defaults:

diff --git a/docs/Makefile b/docs/Makefile
@@ -17,17 +17,18 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
-	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+		@rsync -r --exclude '.ipynb_checkpoints/' ../notebooks/ ./notebooks/
+		@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
-notebooks:
-	rm notebooks/*
-	cp ../notebooks/??_*.ipynb notebooks/.
+github:
+		@make html
 
 sync:
-	@rsync -avh --exclude '.nojekyll' _build/html/ ../docs/ --delete
-	@make clean
+		@rsync -avh _build/html/ ../docs/ --delete
+		@make clean
+		touch .nojekyll
 
 clean:
-	rm -rf $(BUILDDIR)/*
-	rm -rf auto_examples/
-
+		rm -rf $(BUILDDIR)/*
+		rm -rf auto_examples/
+		rm -rf generated/
diff --git a/docs/_static/pysal-styles.css b/docs/_static/pysal-styles.css
@@ -1,12 +1,12 @@
 /* Make thumbnails with equal heights */
-@media only screen and (min-width : 481px) {
+@media only screen and (min-width : 500px) {
     .row.equal-height {
         display: flex;
         flex-wrap: wrap;
     }
     .row.equal-height > [class*='col-'] {
         display: flex;
-        flex-direction: column;
+        flex-direction: row, column;
     }
     .row.equal-height.row:after,
     .row.equal-height.row:before {
@@ -16,15 +16,15 @@
     .row.equal-height > [class*='col-'] > .thumbnail,
     .row.equal-height > [class*='col-'] > .thumbnail > .caption {
         display: flex;
-        flex: 1 0 auto;
+        flex: .9 .1 auto;
         flex-direction: column;
     }
     .row.equal-height > [class*='col-'] > .thumbnail > .caption > .flex-text {
         flex-grow: 1;
     }
     .row.equal-height > [class*='col-'] > .thumbnail > img {
-        width: 100%;
-        height: 200px; /* force image's height */
+        width: 350px;
+        height: 200%; /* force image's height */
 
         /* force image fit inside it's "box" */
         -webkit-object-fit: cover;
@@ -69,5 +69,22 @@
 
 
 /* Table with a scrollbar */
-.bodycontainer { max-height: 600px; width: 100%; margin: 0; overflow-y: auto; }
-.table-scrollable { margin: 0; padding: 0; }
+.bodycontainer { max-height: 800px; width: 100%; margin: 0; padding: 0; overflow-y: auto; }
+.table-scrollable { margin: 0; padding: 0; }
+
+   .label {
+      color: #E74C3C;
+      font-size: 100%;
+      font-weight: bold;
+      width: 100px;
+      text-align: left;
+      vertical-align: middle;
+}
+
+  div.body {
+     max-width: 1080px;
+ }
+
+table.longtable.align-default{
+    text-align: left;
+}
diff --git a/docs/api.rst b/docs/api.rst
@@ -25,8 +25,8 @@ Classifiers
     mapclassify.MaxP
     mapclassify.MaximumBreaks
     mapclassify.NaturalBreaks
-    mapclassify.Quantiles
     mapclassify.Percentiles
+    mapclassify.Quantiles
     mapclassify.StdMean
     mapclassify.UserDefined
 
@@ -37,5 +37,6 @@ Utilities
    :toctree: generated/
 
     mapclassify.KClassifiers
-    mapclassify.gadf
+    mapclassify.Pooled
     mapclassify.classify
+    mapclassify.gadf
diff --git a/docs/conf.py b/docs/conf.py
@@ -48,6 +48,7 @@
     "nbsphinx",
 ]
 
+bibtex_bibfiles = ["_static/references.bib"]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
@@ -79,7 +80,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -116,7 +117,7 @@
 #
 html_theme_options = {
     # Navigation bar title. (Default: ``project`` value)
-    "navbar_title": "mapclassify",  # string of your project name, for example, 'giddy'
+    "navbar_title": project,  # string of your project name, for example, 'giddy'
     # Render the next and previous page links in navbar. (Default: true)
     "navbar_sidebarrel": False,
     # Render the current pages TOC in the navbar. (Default: true)
@@ -175,7 +176,7 @@
 # -- Options for HTMLHelp output ------------------------------------------
 
 # Output file base name for HTML help builder.
-htmlhelp_basename = "mapclassify" + "doc"
+htmlhelp_basename = project + "doc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
@@ -201,8 +202,8 @@
 latex_documents = [
     (
         master_doc,
-        "mapclassify.tex",
-        "mapclassify Documentation",
+        f"{project}.tex",
+        f"{project} Documentation",
         "pysal developers",
         "manual",
     ),
@@ -213,7 +214,7 @@
 
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
-man_pages = [(master_doc, "mapclassify", "mapclassify Documentation", [author], 1)]
+man_pages = [(master_doc, project, f"{project} Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
@@ -224,8 +225,8 @@
 texinfo_documents = [
     (
         master_doc,
-        "mapclassify",
-        "mapclassify Documentation",
+        project,
+        f"{project} Documentation",
         author,
         "PySAL Developers",
         "map classification schemes.",
@@ -240,19 +241,76 @@
 
 # Generate the API documentation when building
 autosummary_generate = True
+
+# avoid showing members twice
 numpydoc_show_class_members = False
 numpydoc_use_plots = True
+class_members_toctree = True
+numpydoc_show_inherited_class_members = True
+numpydoc_xref_param_type = True
+
+# automatically document class members
+autodoc_default_options = {"members": True, "undoc-members": True}
 
 # display the source code for Plot directive
 plot_include_source = True
 
-# automatically document class members
-autodoc_default_options = {"members": True}
-
 
 def setup(app):
-    app.add_stylesheet("pysal-styles.css")
+    app.add_css_file("pysal-styles.css")
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {"https://docs.python.org/3.6/": None}
+intersphinx_mapping = {
+    "geopandas": ("https://geopandas.org/en/latest/", None),
+    "libpysal": ("https://pysal.org/libpysal/", None),
+    "matplotlib": ("https://matplotlib.org/stable/", None),
+    "networkx": ("https://networkx.org/documentation/stable/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "pandas": ("https://pandas.pydata.org/pandas-docs/stable/", None),
+    "python": ("https://docs.python.org/3.11/", None),
+    "scipy": ("https://docs.scipy.org/doc/scipy/", None),
+}
+
+
+# This is processed by Jinja2 and inserted before each notebook
+nbsphinx_prolog = r"""
+{% set docname = env.doc2path(env.docname, base=None) %}
+.. only:: html
+
+    .. role:: raw-html(raw)
+        :format: html
+
+    .. nbinfo::
+
+        This page was generated from `{{ docname }}`__.
+        Interactive online version:
+        :raw-html:`<a href="https://mybinder.org/v2/gh/pysal/mapclassify/main?filepath={{ docname }}"><img alt="Binder badge" src="https://mybinder.org/badge_logo.svg" style="vertical-align:text-bottom"></a>`
+
+    __ https://github.com/pysal/mapclassify/blob/main/{{ docname }}
+.. raw:: latex
+
+    \nbsphinxstartnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{The following section was generated from
+    \sphinxcode{\sphinxupquote{\strut {{ docname | escape_latex }}}} \dotfill}}
+"""
+
+# This is processed by Jinja2 and inserted after each notebook
+nbsphinx_epilog = r"""
+.. raw:: latex
+
+    \nbsphinxstopnotebook{\scriptsize\noindent\strut
+    \textcolor{gray}{\dotfill\ \sphinxcode{\sphinxupquote{\strut
+    {{ env.doc2path(env.docname, base='doc') | escape_latex }}}} ends here.}}
+"""
+
+# List of arguments to be passed to the kernel that executes the notebooks:
+nbsphinx_execute_arguments = [
+    "--InlineBackend.figure_formats={'svg', 'pdf'}",
+    "--InlineBackend.rc={'figure.dpi': 96}",
+]
+
+
+mathjax3_config = {
+    "TeX": {"equationNumbers": {"autoNumber": "AMS", "useLabelIds": True}},
+}
diff --git a/docs/index.rst b/docs/index.rst
@@ -15,29 +15,32 @@ mapclassify is an open-source python library for Choropleth map classification.
             <a href="http://nbviewer.jupyter.org/github/pysal/mapclassify/blob/master/notebooks/03_choropleth.ipynb" class="thumbnail">
                 <img src="_static/images/equalinterval.png" class="img-responsive center-block">
                 <div class="caption text-center">
-                <h6>Equal Interval</h6>
+                <h5>Equal Interval</h5>
                 </div>
             </a>
         </div>
+        <div class="col-sm-1 col-xs-hidden">
+        </div>
         <div class="col-sm-3 col-xs-12">
             <a href="http://nbviewer.jupyter.org/github/pysal/mapclassify/blob/master/notebooks/03_choropleth.ipynb" class="thumbnail">
                 <img src="_static/images/quantiles.png" class="img-responsive center-block">
                 <div class="caption text-center">
-                <h6>Quantiles</h6>
+                <h5>Quantiles</h5>
                 </div>
             </a>
         </div>
+        <div class="col-sm-1 col-xs-hidden">
+        </div>
         <div class="col-sm-3 col-xs-12">
             <a href="http://nbviewer.jupyter.org/github/pysal/mapclassify/blob/master/notebooks/03_choropleth.ipynb" class="thumbnail">
                 <img src="_static/images/fisherjenks.png"
                 class="img-responsive center-block">
                 <div class="caption text-center">
-                <h6>Fisher Jenks
-                </h6>
+                <h5>Fisher Jenks</h5>
                 </div>
             </a>
         </div>
-        <div class="col-sm-2 col-xs-hidden">
+        <div class="col-sm-1 col-xs-hidden">
         </div>
       </div>
     </div>

diff --git a/docs/installation.rst b/docs/installation.rst
@@ -41,9 +41,9 @@ your fork. By making changes
 to your local clone and submitting a pull request to `pysal/mapclassify`_, you can
 contribute to mapclassify development.
 
-.. _3.6: https://docs.python.org/3.8/
-.. _3.7: https://docs.python.org/3.9/
-.. _3.8: https://docs.python.org/3.10/
+.. _3.8: https://docs.python.org/3.8/
+.. _3.9: https://docs.python.org/3.9/
+.. _3.10: https://docs.python.org/3.10/
 .. _conda: https://docs.conda.io/en/latest/
 .. _conda-forge: https://anaconda.org/conda-forge/mapclassify
 .. _Python Package Index: https://pypi.org/project/mapclassify/