Merge pull request #3378 from jsiirola/doc-index

Autogenerate API documentation

Author: jsiirola

doc/Archive/contributed_packages/parmest/driver.rst

@@ -6,7 +6,7 @@ Parameter Estimation
 Parameter Estimation using parmest requires a Pyomo model, experimental
 data which defines multiple scenarios, and parameters
 (thetas) to estimate.  parmest uses Pyomo [PyomoBookII]_ and (optionally) 
-mpi-sppy [mpisppy]_ to solve a
+mpi-sppy [KMM+23]_ to solve a
 two-stage stochastic programming problem, where the experimental data is
 used to create a scenario tree.  The objective function needs to be
 written with the Pyomo Expression for first stage cost

doc/OnlineDocs/Makefile

@@ -7,6 +7,7 @@ SPHINXBUILD   = sphinx-build
 SPHINXPROJ    = Pyomo
 SOURCEDIR     = .
 BUILDDIR      = _build
+APIDIR        = api
 
 # Put it first so that "make" without argument is like "make help".
 help:
@@ -23,9 +24,9 @@ clean:
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@echo "Removing *.spy, *.out"
 	@find . -name \*.spy -delete
+	@for D in $(BUILDDIR) $(SOURCEDIR)/$(APIDIR); do \
+	    if test -d "$$D"; then echo "Removing $$D"; rm -r "$$D"; fi \
+	 done
 
 rebuild:
 	@$(MAKE) clean
-	@for D in $(BUILDDIR) $(SOURCEDIR)/reference/API; do \
-	    if test -d "$$D"; then echo "Removing $$D"; rm -r "$$D"; fi \
-	 done

doc/OnlineDocs/README.md

@@ -0,0 +1,58 @@
+Pyomo leverages ``make`` to generate documentation.  The following two
+sections describe how to build and test the online documentation
+locally.
+
+.. note::
+
+   All commands assume you are running from the `root Pyomo source directory`.
+
+
+Preview Changes Locally
+------------------------
+
+1. Install documentation dependencies (e.g., Sphinx, etc):
+
+   ```bash
+   $ pip install -e .[docs]
+   ```
+   
+   **NOTE**: You may get a warning about the `dot` command if you do not have
+   `graphviz` installed.
+
+2. Build the documentation.  Sphinx (and Pyomo) support multiple
+   documentation `targets`.  These instructions describe building the
+   `html` target, but the same process applies for other targets.
+
+   ```bash
+   $ make -C doc/OnlineDocs html
+   ```
+
+3. View ``doc/OnlineDocs/_build/html/index.html`` in your browser
+
+Test Changes Locally
+--------------------
+
+   ```bash
+   $ make -C doc/OnlineDocs doctest
+   ```
+
+Rebuilding the documentation
+----------------------------
+
+Sphinx caches significant amounts of work at the end of a documentation
+build.  However, if you are in the process of editing the documentation,
+it may not correctly invalidate the cache.  You can purge the entire
+cache with
+
+   ```bash
+   $ make -C doc/OnlineDocs clean
+   ```
+
+Combining steps
+---------------
+
+These steps can, of course, be combined into a single command:
+
+   ```bash
+   $ make -c doc/OnlineDocs clean html doctest
+   ```

doc/OnlineDocs/_templates/recursive-base.rst

@@ -0,0 +1,13 @@
+{{ name | escape | underline}}
+
+({{ objtype }} from :py:mod:`{{ module }}`)
+
+.. testsetup:: *
+
+   # import everything from the module containing this class so that
+   # doctests for the class docstrings see the correct environment
+   from {{ module }} import *
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

doc/OnlineDocs/_templates/recursive-class.rst

@@ -0,0 +1,47 @@
+{{ name | escape | underline}}
+
+(class from :py:mod:`{{ module }}`)
+
+.. testsetup:: *
+
+   # import everything from the module containing this class so that
+   # doctests for the class docstrings see the correct environment
+   from {{ module }} import *
+
+.. currentmodule:: {{ module }}
+
+{# Note that numpy.ndarray examples fail doctest; disable documentation
+   of inherited members for classes derived from ndarray #}
+
+.. autoclass:: {{ objname }}
+   :members:
+   :show-inheritance:
+   {{ '' if (module + '.' + name) in (
+         'pyomo.contrib.pynumero.sparse.block_vector.BlockVector',
+         'pyomo.contrib.pynumero.sparse.mpi_block_vector.MPIBlockVector',
+         'pyomo.core.expr.ndarray.NumericNDArray',
+      ) else ':inherited-members:' }}
+
+   {% block methods %}
+   .. automethod:: __init__
+
+   {% if methods %}
+   .. rubric:: {{ _('Methods') }}
+
+   .. autosummary::
+   {% for item in methods %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      ~{{ name }}.{{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}

doc/OnlineDocs/_templates/recursive-module.rst

@@ -0,0 +1,79 @@
+{% if fullname == 'pyomo' %}
+Library Reference
+=================
+{% else %}
+{{ name | escape | underline}}
+{% endif %}
+
+.. automodule:: {{ fullname }}
+   :undoc-members:
+
+   {% block attributes %}
+   {%- if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: recursive-base.rst
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block functions %}
+   {%- if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+      :toctree:
+      :template: recursive-base.rst
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block classes %}
+   {%- if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+      :toctree:
+      :template: recursive-class.rst
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+   {%- block exceptions %}
+   {%- if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+      :toctree:
+      :template: recursive-class.rst
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {%- endblock %}
+
+{%- block modules %}
+{%- if modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :template: recursive-module.rst
+   :recursive:
+{% for item in modules %}
+{# Need item != tests for Sphinx >= 8.0; !endswith(.tests) for < 8.0 #}
+{% if item != 'tests' and not item.endswith('.tests')
+   and item != 'examples' and not item.endswith('.examples') %}
+   {{ item }}
+{% endif %}
+{%- endfor %}
+{% endif %}
+{%- endblock %}

doc/OnlineDocs/code.rst

@@ -0,0 +1,9 @@
+:orphan:
+
+.. autosummary::
+   :toctree: api
+   :caption: Library Reference
+   :template: recursive-module.rst
+   :recursive:
+
+   pyomo

doc/OnlineDocs/conf.py

@@ -58,7 +58,6 @@
     'pandas': ('https://pandas.pydata.org/docs/', None),
     'scikit-learn': ('https://scikit-learn.org/stable/', None),
     'scipy': ('https://docs.scipy.org/doc/scipy/', None),
-    'Sphinx': ('https://www.sphinx-doc.org/en/master/', None),
 }
 
 # -- General configuration ------------------------------------------------
@@ -84,8 +83,6 @@
     'sphinx.ext.todo',
     'sphinx_copybutton',
     'enum_tools.autoenum',
-    'sphinx.ext.autosectionlabel',
-    #'sphinx.ext.githubpages',
 ]
 
 viewcode_follow_imported_members = True
@@ -108,7 +105,7 @@
 
 # General information about the project.
 project = u'Pyomo'
-copyright = u'2008-2023, Sandia National Laboratories'
+copyright = u'2008-2024, Sandia National Laboratories'
 author = u'Pyomo Developers'
 
 # The version info for the project you're documenting, acts as replacement for
@@ -132,7 +129,21 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+# Notes:
+#  - _build : this is the Sphinx build (output) dir
+#
+#  - api/*.tests.* : this matches autosummary RST files generated for
+#    test modules.  Note that the _templates/recursive-modules.rst
+#    should prevent these file from being generated, so this is not
+#    strictly necessary, but including it makes Sphinx throw warnings if
+#    the filter in the template ever "breaks"
+#
+#  - **/tests/** : this matches source files in any tests directory
+#    [JDS: I *believe* this is necessary, but am not 100% certain]
+#
+#  - 'Thumbs.db', '.DS_Store' : these have been included from the
+#    beginning.  Unclear if they are still necessary
+exclude_patterns = ['_build', 'api/*.tests.*', '**/tests/**', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -168,7 +179,7 @@
 # further.  For a list of options available for each theme, see the
 # documentation.
 #
-# html_theme_options = {}
+html_theme_options = {'navigation_depth': 6, 'titles_only': True}
 
 # 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,
@@ -235,6 +246,9 @@
 # autodoc_member_order = 'bysource'
 # autodoc_member_order = 'groupwise'
 
+autosummary_generate = True
+autosummary_ignore_module_all = True
+
 # -- Check which conditional dependencies are available ------------------
 # Used for skipping certain doctests
 from sphinx.ext.doctest import doctest
@@ -267,20 +281,25 @@ def check_output(self, want, got, optionflags):
     platform.python_implementation()
 )
 
+# We need multiprocessing because some doctests must be skipped if the
+# start method is not "fork"
+import multiprocessing
+
+# (register plugins, make environ available to tests)
+import pyomo.environ as pyo
+
 from pyomo.common.dependencies import (
     attempt_import, numpy_available, scipy_available, pandas_available,
     yaml_available, networkx_available, matplotlib_available,
-    pympler_available, dill_available,
+    pympler_available, dill_available, pint_available,
+    numpy as np,
 )
-pint_available = attempt_import('pint', defer_import=False)[1]
 from pyomo.contrib.parmest.parmest import parmest_available
 
-import pyomo.environ as _pe # (trigger all plugin registrations)
-import pyomo.opt as _opt
-
 # Not using SolverFactory to check solver availability because
 # as of June 2020 there is no way to suppress warnings when 
 # solvers are not available
+import pyomo.opt as _opt
 ipopt_available = bool(_opt.check_available_solvers('ipopt'))
 sipopt_available = bool(_opt.check_available_solvers('ipopt_sens'))
 k_aug_available = bool(_opt.check_available_solvers('k_aug'))
@@ -291,6 +310,11 @@ def check_output(self, want, got, optionflags):
 
 baron = _opt.SolverFactory('baron')
 
+if numpy_available:
+    # Recent changes on GHA seem to have dropped the default precision
+    # from 8 to 4; restore the default.
+    np.set_printoptions(precision=8)
+
 if numpy_available and scipy_available:
     import pyomo.contrib.pynumero.asl as _asl
     asl_available = _asl.AmplInterface.available()
@@ -302,6 +326,11 @@ def check_output(self, want, got, optionflags):
     ma27_available = False
     mumps_available = False
 
+# Mark that we are testing code (in this case, testing the documentation)
 from pyomo.common.flags import in_testing_environment
 in_testing_environment(True)
+
+# Prevent any Pyomo logs from propagating up to the doctest logger
+import logging
+logging.getLogger('pyomo').propagate = False
 '''

doc/OnlineDocs/explanation/analysis/alternative_solutions.rst

@@ -94,14 +94,20 @@ Interface Documentation
 .. currentmodule:: pyomo.contrib.alternative_solutions
 
 .. autofunction:: enumerate_binary_solutions
+   :noindex:
 
 .. autofunction:: enumerate_linear_solutions
+   :noindex:
 
 .. autofunction:: pyomo.contrib.alternative_solutions.lp_enum_solnpool.enumerate_linear_solutions_soln_pool
+   :noindex:
 
 .. autofunction:: gurobi_generate_solutions
+   :noindex:
 
 .. autofunction:: obbt_analysis_bounds_and_solutions
+   :noindex:
 
 .. autoclass:: Solution
+   :noindex: