Autogenerate API documentation

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,6 +24,7 @@ clean:
 	@$(SPHINXBUILD) -M clean "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@echo "Removing *.spy, *.out"
 	@find . -name \*.spy -delete
+	@if test -d "$(SOURCEDIR)/${APIDIR}"; then rm -r "$(SOURCEDIR)/${APIDIR}"; fi
 
 rebuild:
 	@$(MAKE) clean

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,77 @@
+{% 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 %}
+{% if '.test' not in item and '.example' not in item %}
+   {{ 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,7 @@
 # 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']
+exclude_patterns = ['_build', '**/tests', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
@@ -168,7 +165,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 +232,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
@@ -271,11 +271,12 @@ def check_output(self, want, got, optionflags):
     attempt_import, numpy_available, scipy_available, pandas_available,
     yaml_available, networkx_available, matplotlib_available,
     pympler_available, dill_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.environ as pyo  # (register plugins, make environ available to tests)
 import pyomo.opt as _opt
 
 # Not using SolverFactory to check solver availability because
@@ -291,6 +292,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 +308,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:
 

doc/OnlineDocs/explanation/analysis/community.rst

@@ -24,7 +24,7 @@ detection. Thus, this package provides the user with a lot of control over the c
 function we use for this community detection is shown below:
 
 .. autofunction:: pyomo.contrib.community_detection.detection.detect_communities
-  :noindex:
+   :noindex:
 
 As stated above, the characteristics of the NetworkX graph of the Pyomo model are very important to the
 community detection. The main graph features the user can specify are the type of community map,
@@ -383,7 +383,9 @@ We can see an example for the three separate graphs created by these three funct
 Functions in this Package
 -------------------------
 .. automodule:: pyomo.contrib.community_detection.detection
+    :noindex:
     :members:
 
 .. automodule:: pyomo.contrib.community_detection.community_graph
+    :noindex:
     :members:

doc/OnlineDocs/explanation/analysis/iis.rst

@@ -3,21 +3,27 @@ Infeasibility Diagnostics
 
 There are two closely related tools for infeasibility diagnosis:
 
-  - :ref:`Infeasible Irreducible System (IIS) Tool`
-  - :ref:`Minimal Intractable System finder (MIS) Tool`
+  - :ref:`iis`
+  - :ref:`mis`
 
 The first simply provides a conduit for solvers that compute an
 infeasible irreducible system (e.g., Cplex, Gurobi, or Xpress).  The
 second provides similar functionality, but uses the ``mis`` package
 contributed to Pyomo.
 
 
+.. _iis:
+
 Infeasible Irreducible System (IIS) Tool
 ========================================
 
 .. automodule:: pyomo.contrib.iis.iis
+   :noindex:
 
 .. autofunction:: pyomo.contrib.iis.write_iis
+   :noindex:
+
+.. _mis:
 
 Minimal Intractable System finder (MIS) Tool
 ============================================

doc/OnlineDocs/explanation/analysis/incidence/config.rst

@@ -2,4 +2,5 @@ Incidence Options
 =================
 
 .. automodule:: pyomo.contrib.incidence_analysis.config
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/connected.rst

@@ -2,4 +2,5 @@ Weakly Connected Components
 ===========================
 
 .. automodule:: pyomo.contrib.incidence_analysis.connected
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/dulmage_mendelsohn.rst

@@ -2,4 +2,5 @@ Dulmage-Mendelsohn Partition
 ============================
 
 .. automodule:: pyomo.contrib.incidence_analysis.dulmage_mendelsohn
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/incidence.rst

@@ -2,4 +2,5 @@ Incident Variables
 ==================
 
 .. automodule:: pyomo.contrib.incidence_analysis.incidence
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/interface.rst

@@ -2,4 +2,5 @@ Pyomo Interfaces
 ================
 
 .. automodule:: pyomo.contrib.incidence_analysis.interface
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/matching.rst

@@ -2,4 +2,5 @@ Maximum Matching
 ================
 
 .. automodule:: pyomo.contrib.incidence_analysis.matching
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/scc_solver.rst

@@ -2,4 +2,5 @@ Block Triangular Decomposition Solver
 =====================================
 
 .. automodule:: pyomo.contrib.incidence_analysis.scc_solver
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/incidence/triangularize.rst

@@ -2,4 +2,5 @@ Block Triangularization
 =======================
 
 .. automodule:: pyomo.contrib.incidence_analysis.triangularize
+   :noindex:
    :members:

doc/OnlineDocs/explanation/analysis/mpc/conversion.rst

@@ -2,4 +2,5 @@ Data Conversion
 ===============
 
 .. automodule:: pyomo.contrib.mpc.data.convert
+   :noindex:
    :members: