Clairify common documentation; update links

doc/OnlineDocs/developer_reference/deprecation.rst

@@ -11,22 +11,33 @@ Deprecation
 We offer a set of tools to help with deprecation in
 ``pyomo.common.deprecation``.
 
-By policy, when deprecating or moving an existing capability,
-one of the following functions should be imported. In use,
-the ``version`` option should be set to current development
-version. This can be found by running ``pyomo --version`` on
-your local fork/branch.
+By policy, when deprecating or moving an existing capability, one of the
+following utilities should be leveraged.  Each has a required
+``version`` argument that should be set to current development version (e.g.,
+``"6.6.2.dev0"``).  This version will be updated to the next actual
+release as part of the Pyomo release process.  The current development version
+can be found by running ``pyomo --version`` on your local fork/branch.
 
-.. autoclass:: pyomo.common.deprecation.deprecated
+.. currentmodule:: pyomo.common.deprecation
+
+.. autosummary::
+
+   deprecated
+   deprecation_warning
+   relocated_module
+   relocated_module_attribute
+   RenamedClass
+
+.. autodecorator:: pyomo.common.deprecation.deprecated
    :noindex:
 
-.. autoclass:: pyomo.common.deprecation.deprecation_warning
+.. autofunction:: pyomo.common.deprecation.deprecation_warning
    :noindex:
 
-.. autoclass:: pyomo.common.deprecation.relocated_module
+.. autofunction:: pyomo.common.deprecation.relocated_module
    :noindex:
 
-.. autoclass:: pyomo.common.deprecation.relocated_module_attribute
+.. autofunction:: pyomo.common.deprecation.relocated_module_attribute
    :noindex:
 
 .. autoclass:: pyomo.common.deprecation.RenamedClass

pyomo/common/dependencies.py

@@ -25,11 +25,11 @@
 
 
 class ModuleUnavailable(object):
-    """Mock object that raises a DeferredImportError upon attribute access
+    """Mock object that raises :py:class:`.DeferredImportError` upon attribute access
 
     This object is returned by :py:func:`attempt_import()` in lieu of
     the module in the case that the module import fails.  Any attempts
-    to access attributes on this object will raise a DeferredImportError
+    to access attributes on this object will raise a :py:class:`.DeferredImportError`
     exception.
 
     Parameters
@@ -131,7 +131,7 @@ class DeferredImportModule(object):
     ``defer_check=True``.  Any attempts to access attributes on this
     object will trigger the actual module import and return either the
     appropriate module attribute or else if the module import fails,
-    raise a DeferredImportError exception.
+    raise a :py:class:`.DeferredImportError` exception.
 
     """
 
@@ -275,11 +275,11 @@ class DeferredImportIndicator(_DeferredImportIndicatorBase):
 
     This object serves as a placeholder for the Boolean indicator if a
     deferred module import was successful.  Casting this instance to
-    bool will cause the import to be attempted.  The actual import logic
-    is here and not in the DeferredImportModule to reduce the number of
-    attributes on the DeferredImportModule.
+    `bool` will cause the import to be attempted.  The actual import logic
+    is here and not in the :py:class:`DeferredImportModule` to reduce the number of
+    attributes on the :py:class:`DeferredImportModule`.
 
-    ``DeferredImportIndicator`` supports limited logical expressions
+    :py:class:`DeferredImportIndicator` supports limited logical expressions
     using the ``&`` (and) and ``|`` (or) binary operators.  Creating
     these expressions does not trigger the import of the corresponding
     :py:class:`DeferredImportModule` instances, although casting the
@@ -524,8 +524,8 @@ def attempt_import(
     defer_check: bool, optional
         If True (the default), then the attempted import is deferred
         until the first use of either the module or the availability
-        flag.  The method will return instances of DeferredImportModule
-        and DeferredImportIndicator.
+        flag.  The method will return instances of :py:class:`DeferredImportModule`
+        and :py:class:`DeferredImportIndicator`.
 
     deferred_submodules: Iterable[str], optional
         If provided, an iterable of submodule names within this module
@@ -673,7 +673,7 @@ def _perform_import(
 
 
 def declare_deferred_modules_as_importable(globals_dict):
-    """Make all DeferredImportModules in ``globals_dict`` importable
+    """Make all :py:class:`DeferredImportModules` in ``globals_dict`` importable
 
     This function will go throughout the specified ``globals_dict``
     dictionary and add any instances of :py:class:`DeferredImportModule`

pyomo/common/deprecation.py

@@ -389,10 +389,6 @@ def relocated_module_attribute(
     object from the new location (on request), as well as emitting the
     deprecation warning.
 
-    It contains backports of the __getattr__ functionality for earlier
-    versions of Python (although the implementation for 3.5+ is more
-    efficient that the implementation for 2.7+)
-
     Parameters
     ----------
     local: str

pyomo/common/errors.py

@@ -122,8 +122,8 @@ class ApplicationError(Exception):
 
 class PyomoException(Exception):
     """
-    Exception class for other pyomo exceptions to inherit from,
-    allowing pyomo exceptions to be caught in a general way
+    Exception class for other Pyomo exceptions to inherit from,
+    allowing Pyomo exceptions to be caught in a general way
     (e.g., in other applications that use Pyomo).
     """