Merge branch 'main' into linear-dual-fix

Author: blnicho

.coin-or/projDesc.xml

@@ -157,7 +157,6 @@ Carl D. Laird, Chair, Pyomo Management Committee, claird at andrew dot cmu dot e
 		<!--         GLPK                                              -->
 		<!--      </packageName>                                       -->
 		<!--      <packageURL>                                         -->
-		<!--         http://www.gnu.org/software/glpk/                 -->
 		<!--      </packageURL>                                        -->
 		<!--      <requiredOrOptional>                                 -->
 		<!--         Optional                                          -->

.github/workflows/test_branches.yml

@@ -44,9 +44,10 @@ jobs:
         python-version: '3.10'
     - name: Black Formatting Check
       run: |
-        # Note v24.4.1 fails due to a bug in the parser
+        # Note v24.4.1 fails due to a bug in the parser. Project-level
+        # configuration is inherited from pyproject.toml.
         pip install 'black!=24.4.1'
-        black . -S -C --check --diff --exclude examples/pyomobook/python-ch/BadIndent.py
+        black . --check --diff
     - name: Spell Check
       uses: crate-ci/typos@master
       with: 
@@ -63,9 +64,13 @@ jobs:
         verbose: true
         # How many times to retry a failed request (defaults to 1)
         retry_count: 3
-        # Exclude Jenkins because it's behind a firewall; ignore RTD because
-        # a magically-generated string is triggering a failure
+        # Exclude:
+        #  - Jenkins because it's behind a firewall
+        #  - RTD because a magically-generated string triggers failures
         exclude_urls: https://pyomo-jenkins.sandia.gov/,https://pyomo.readthedocs.io/en/%s/errors.html
+        # Exclude:
+        #  - All gnu.org links because they consistently fail the checker
+        exclude_patterns: https://www.gnu.org
 
 
   build:

.github/workflows/test_pr_and_main.yml

@@ -55,9 +55,10 @@ jobs:
         python-version: '3.10'
     - name: Black Formatting Check
       run: |
-        # Note v24.4.1 fails due to a bug in the parser
+        # Note v24.4.1 fails due to a bug in the parser. Project-level
+        # configuration is inherited from pyproject.toml.
         pip install 'black!=24.4.1'
-        black . -S -C --check --diff --exclude examples/pyomobook/python-ch/BadIndent.py
+        black . --check --diff
     - name: Spell Check
       uses: crate-ci/typos@master
       with: 
@@ -74,9 +75,13 @@ jobs:
         verbose: true
         # How many times to retry a failed request (defaults to 1)
         retry_count: 3
-        # Exclude Jenkins because it's behind a firewall; ignore RTD because
-        # a magically-generated string is triggering a failure
+        # Exclude:
+        #  - Jenkins because it's behind a firewall
+        #  - RTD because a magically-generated string triggers failures
         exclude_urls: https://pyomo-jenkins.sandia.gov/,https://pyomo.readthedocs.io/en/%s/errors.html
+        # Exclude:
+        #  - All gnu.org links because they consistently fail the checker
+        exclude_patterns: https://www.gnu.org
 
 
   build:

.github/workflows/url_check.yml

@@ -30,3 +30,6 @@ jobs:
         #  - Jenkins because it's behind a firewall
         #  - RTD because a magically-generated string triggers failures
         exclude_urls: https://pyomo-jenkins.sandia.gov/,https://pyomo.readthedocs.io/en/%s/errors.html
+        # Exclude:
+        #  - All gnu.org links because they consistently fail the checker
+        exclude_patterns: https://www.gnu.org

doc/OnlineDocs/_templates/recursive-base.rst

@@ -15,4 +15,4 @@
 
 .. currentmodule:: {{ module }}
 
-.. auto{{ objtype }}:: {{ objname }}
+.. auto{{ objtype }}:: {{ module }}::{{ objname }}

doc/OnlineDocs/conf.py

@@ -162,6 +162,94 @@
 # they have a caption.
 numfig = True
 
+
+# We want to be able to document the CONFIG class attribute in a special
+# section.  Nominally, we would use the napoleon_custom_sections hook.
+# Unfortunately, there isn't a generic "kwargs_style", and aliasing
+# 'Keyword Arguments' would render the section header in the
+# documentation as 'Keyword Arguments'.
+#
+# Our solution is to declare a new PyObject field type (:config:) and
+# define a new parser that generates :config: fields.  We register the
+# new parser with Napoleon by monkey-patching _load_custom_sections().
+def _monkey_patch_napoleon():
+    from sphinx.ext.napoleon.docstring import GoogleDocstring
+    from sphinx.domains.python._object import PyObject, PyTypedField
+    from sphinx.locale import _
+    from sphinx import addnodes
+    from functools import partial
+
+    class PyConfigDomainField(PyTypedField):
+        def make_xref(
+            self,
+            rolename: str,
+            domain: str,
+            target: str,
+            innernode=addnodes.literal_emphasis,
+            contnode=None,
+            env=None,
+            inliner=None,
+            location=None,
+        ):
+            ans = super().make_xref(
+                rolename=rolename,
+                domain=domain,
+                target=target,
+                innernode=innernode,
+                contnode=contnode,
+                env=env,
+                inliner=inliner,
+                location=location,
+            )
+            # Part of the call stack will override the reftype to
+            # "class".  We want to support a broader set of domain
+            # types, so we will set it to "anything" (i.e., object)
+            ans['reftype'] = 'obj'
+            return ans
+
+    PyObject.doc_field_types.append(
+        PyConfigDomainField(
+            'config',
+            label=_('CONFIG'),
+            names=('config',),
+            typerolename='obj',
+            typenames=('configtype',),
+            can_collapse=True,
+        )
+    )
+    PyObject.doc_field_types.append(
+        PyConfigDomainField(
+            'option',
+            label=_('Options'),
+            names=('option',),
+            typerolename='obj',
+            typenames=('optiontype',),
+            can_collapse=True,
+        )
+    )
+
+    def _parse_config_section(self, field: str, section: str) -> list[str]:
+        fields = self._consume_fields()
+        if self._config.napoleon_use_keyword:
+            return self._format_docutils_params(
+                fields, field_role=field, type_role=field + 'type'
+            )
+        else:
+            return self._format_fields(_(section), fields)
+
+    original_loader = GoogleDocstring._load_custom_sections
+
+    def _load_custom_sections(self):
+        self._sections['config'] = partial(self._parse_config_section, 'config')
+        self._sections['options'] = partial(self._parse_config_section, 'option')
+        return original_loader(self)
+
+    GoogleDocstring._parse_config_section = _parse_config_section
+    GoogleDocstring._load_custom_sections = _load_custom_sections
+
+
+_monkey_patch_napoleon()
+
 # -- Options for HTML output ----------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

doc/OnlineDocs/contribution_guide.rst

@@ -37,13 +37,17 @@ run:
 
     # Auto-apply correct formatting
    pip install black
-   black -S -C <path> --exclude examples/pyomobook/python-ch/BadIndent.py
+   black <path>
    # Find typos in files
    conda install typos
    typos --config .github/workflows/typos.toml <path>
    
-If the spell-checker returns a failure for a word that is spelled correctly,
-please add the word to the ``.github/workflows/typos.toml`` file.
+If the spell-checker returns a failure for a word that is spelled
+correctly, please add the word to the ``.github/workflows/typos.toml``
+file. Note also that ``black`` reads from ``pyproject.toml`` to
+determine correct configuration, so if you are running ``black``
+indirectly (for example, using an IDE integration), please ensure you
+are not overriding the project-level configuration set in that file.
 
 Online Pyomo documentation is generated using `Sphinx <https://www.sphinx-doc.org/en/master/>`_
 with the ``napoleon`` extension enabled. For API documentation we use of one of these 
@@ -332,7 +336,7 @@ Finally, move to the directory containing the clone of your Pyomo fork and run:
 
 ::
 
-  python setup.py develop
+  pip install -e .
 
 These commands register the cloned code with the active python environment
 (``pyomodev``). This way, your changes to the source code for ``pyomo`` are

doc/OnlineDocs/explanation/analysis/parmest/driver.rst

@@ -98,7 +98,7 @@ List of experiment objects
 --------------------------
 
 The first argument is a list of experiment objects which is used to
-create one labeled model for each expeirment. 
+create one labeled model for each experiment. 
 The template :class:`~pyomo.contrib.parmest.experiment.Experiment` 
 can be used to generate a list of experiment objects.