Clean up parameters documentation

- Mostly reformats docs to be rendered by jupyter books
- Clarifies some grammer/long sentences
- Removes inherited ParamTools methods from the docs
  and replaces them with a link to the ParamTools docs

docs/api/parameters.rst

@@ -10,14 +10,8 @@ taxcalc.parameters
 
 .. currentmodule:: taxcalc.parameters
 
-.. autoclass:: CompatibleDataSchema
-  :members: 
-
 .. autoclass:: Parameters
   :members: adjust, adjust_with_indexing, get_index_rate, set_rates,
-    wage_growth_rates, inflation_rates, initialize, set_state,
-    clear_state, view_state, read_params, adjust, delete, specification,
-    to_array, from_array, extend, extend_func, get_index_rate,
-    select_eq, select_ne, select_gt, select_gte, select_lte,
-    keys, items, to_dict, sort_values, parse_label, _update,
-    _read_json_revision, metadata, years_in_revisionm, __getattr__
+    wage_growth_rates, inflation_rates, initialize,
+    _update, _read_json_revision, metadata, years_in_revision,
+    __getattr__

taxcalc/parameters.py

@@ -16,9 +16,13 @@
 class CompatibleDataSchema(ma.Schema):
     """
     Schema for Compatible data object
-    {
-        "compatible_data": {"data1": bool, "data2": bool, ...}
-    }
+
+    .. code-block :: json
+
+        {
+            "compatible_data": {"puf": true, "cps": false}
+        }
+
     """
 
     puf = ma.fields.Boolean()
@@ -33,24 +37,36 @@ class CompatibleDataSchema(ma.Schema):
 
 class Parameters(pt.Parameters):
     """
-    Base Parameters class that wraps ParamTools, providing parameter indexing
-    for tax policy in the adjust method and backwards-compatible preserving
-    layer that supports Tax-Calculator's conventional reform formatting style
-    as well as convenience methods like set_Year for classes operating on this
-    one.
+    Base class that wraps ParamTools, providing parameter indexing
+    for tax policy in the ``adjust`` method and convenience methods
+    like ``set_year`` for classes inheriting from it. It also provides
+    a backwards-compatible layer for Tax-Calculator versions prior to 3.0.
 
     The defaults file path may be set through the defaults class attribute
-    variable or through the old DEFAULTS_FILE_NAME/DEFAULTS_FILE_PATH work
-    flow.
+    variable or through the ``DEFAULTS_FILE_NAME`` /
+    ``DEFAULTS_FILE_PATH work`` flow.
 
     A custom getter method is implemented so that the value of a parameter
     over all allowed years can conveniently be retrieved by adding an
-    underscore before the variable name (e.g. EITC_c vs _EITC_c).
+    underscore before the variable name (e.g. ``EITC_c`` vs ``_EITC_c``).
+
+    This class inherits methods from ParamTools like ``items``:
+
+        .. code-block :: python
+
+            import taxcalc as tc
+            pol = tc.Policy()
+
+            for name, value in pol.items():
+                print(name, value)
 
-    Note: Like all pt.Parameters classes the values of attributes
-    corresponding to a parameter value on this class are ephemeral and the only
-    way to make permanent changes to this class'sstate is through the set_state
-    or adjust methods.
+            # parameter_indexing_CPI_offset [0.]
+            # FICA_ss_trt [0.124]
+            # SS_Earnings_c [113700.]
+
+    Check out the ParamTools
+    `documentation <https://paramtools.dev/api/reference.html>`_
+    for more information on these inherited methods.
 
     """
     defaults = None
@@ -116,12 +132,36 @@ def adjust(
         self, params_or_path, print_warnings=True, raise_errors=True, **kwargs
     ):
         """
-        Implements custom warning and error handling.
-        If print_warnings is True, warnings are printed out and if
-        print_warnings is False, nothing is printed.
-        ParamTools throws an error if a warning is triggered and
-        ignore_warnings is False. This method circumvents this behavior.
-        """
+        Update parameter values using a ParamTools styled adjustment.
+
+        Parameters
+        ----------
+        params_or_path : Dict, str
+            New parameter values in the paramtools format. For example:
+
+            .. code-block:: json
+
+                {
+                    "standard_deduction": [
+                        {"year": 2024, "marital_status": "single", "value": 10000.0},
+                        {"year": 2024, "marital_status": "joint", "value": 10000.0}
+                    ],
+                    "ss_rate": [{"year": 2024, "value": 0.2}]}
+                }
+
+        print_warnings : Boolean
+            Print parameter warnings or not
+        raise_errors: Boolean
+            Raise errors as a ValidationError. If False, they will be stored
+            in the errors attribute.
+
+
+        Returns
+        -------
+        adjustment : Dict
+            Parsed paremeter dictionary
+
+        """  # noqa
         if print_warnings:
             _data = copy.deepcopy(self._data)
             kwargs["ignore_warnings"] = False
@@ -130,6 +170,9 @@ def adjust(
         self._warnings = {}
         self._errors = {}
         try:
+            # Wrap all updates in adjust_with_indexing in a transaction and
+            # defer related-parameter validation until all intermediate updates
+            # are complete.
             with self.transaction(
                 defer_validation=True,
                 raise_errors=True,
@@ -159,45 +202,52 @@ def adjust(
 
     def adjust_with_indexing(self, params_or_path, **kwargs):
         """
-        Custom adjust method that handles special indexing logic. The logic
-        is:
+        Adjust parameter values with the following indexing logic:
 
         1. If "parameter_indexing_CPI_offset" is adjusted, first set
-        parameter_indexing_CPI_offset to zero before implementing the
-        adjusted parameter_indexing_CPI_offset to avoid stacking adjustments.
-        Then, revert all values of indexed parameters to the 'known' values:
+           parameter_indexing_CPI_offset to zero before implementing the
+           adjusted parameter_indexing_CPI_offset to avoid stacking
+           adjustments. Then, revert all values of indexed parameters to
+           the 'known' values:
+
             a. The current values of parameters that are being adjusted are
-                deleted after the first year in which
-                parameter_indexing_CPI_offset is adjusted.
+               deleted after the first year in which
+               parameter_indexing_CPI_offset is adjusted.
             b. The current values of parameters that are not being adjusted
-                (i.e. are not in params) are deleted after the last known year,
-                with the exception of parameters that revert to their pre-TCJA
-                values in 2026. Instead, these (2026) parameter values are
-                recalculated using the new inflation rates.
+               (i.e. are not in params) are deleted after the last known year,
+               with the exception of parameters that revert to their pre-TCJA
+               values in 2026. Instead, these (2026) parameter values are
+               recalculated using the new inflation rates.
+
             After the 'unknown' values have been deleted, the last known value
             is extrapolated through the budget window. If there are indexed
             parameters in the adjustment, they will be included in the final
             adjustment call (unless their indexed status is changed).
+
         2. If the "indexed" status is updated for any parameter:
+
             a. If a parameter has values that are being adjusted before
-                the indexed status is adjusted, update those parameters first.
+               the indexed status is adjusted, update those parameters first.
             b. Extend the values of that parameter to the year in which
-                the status is changed.
+               the status is changed.
             c. Change the indexed status for the parameter.
             d. Update parameter values in adjustment that are adjusted after
-                the year in which the indexed status changes.
+               the year in which the indexed status changes.
             e. Using the new "-indexed" status, extend the values of that
-                parameter through the remaining years or until the -indexed
-                status changes again.
+               parameter through the remaining years or until the -indexed
+               status changes again.
+
         3. Update all parameters that are not indexing related, i.e. they are
-            not "parameter_indexing_CPI_offset" or do not end with "-indexed".
+           not "parameter_indexing_CPI_offset" or do not end with "-indexed".
+
         4. Return parsed adjustment with all adjustments, including "-indexed"
-            parameters.
+           parameters.
 
         Notable side-effects:
-            - All values of a parameter whose indexed status is adjusted are
-              wiped out after the year in which the value is adjusted for the
-              same hard-coding reason.
+
+        - All values of a parameter whose indexed status is adjusted are
+          wiped out after the year in which the value is adjusted for the
+          same hard-coding reason.
         """
         # Temporarily turn off extra ops during the intermediary adjustments
         # so that expensive and unnecessary operations are not run.
@@ -507,29 +557,33 @@ def initialize(self, start_year, num_years, last_known_year=None,
 
     def _update(self, revision, print_warnings, raise_errors):
         """
-        A translation layer on top of Parameters.adjust. Projects
-        that have historically used the `_update` method with
+        A translation layer on top of ``adjust``. Projects
+        that have historically used the ``_update`` method with
         Tax-Calculator styled adjustments can continue to do so
         without making any changes to how they handle adjustments.
 
         Converts reforms that are compatible with Tax-Calculator:
 
-        adjustment = {
-            "standard_deduction": {2024: [10000.0, 10000.0]},
-            "ss_rate": {2024: 0.2}
-        }
+        .. code-block:: python
+
+            adjustment = {
+                "standard_deduction": {2024: [10000.0, 10000.0]},
+                "ss_rate": {2024: 0.2}
+            }
 
         into reforms that are compatible with ParamTools:
 
-        {
-            'standard_deduction': [
-                {'year': 2024, 'marital_status': 'single', 'value': 10000.0},
-                {'year': 2024, 'marital_status': 'joint', 'value': 10000.0}
-            ],
-            'ss_rate': [{'year': 2024, 'value': 0.2}]}
-        }
+        .. code-block:: python
 
-        """
+            {
+                "standard_deduction": [
+                    {"year": 2024, "marital_status": "single", "value": 10000.0},
+                    {"year": 2024, "marital_status": "joint", "value": 10000.0}
+                ],
+                "ss_rate": [{"year": 2024, "value": 0.2}]}
+            }
+
+        """  # noqa: E501
         if not isinstance(revision, dict):
             raise pt.ValidationError(
                 {"errors": {"schema": "Revision must be a dictionary."}},
@@ -747,8 +801,9 @@ def years_in_revision(revision):
 
     def __getattr__(self, attr):
         """
-        Allows the user to get the value of a parameter over all years,
-        not just the ones that are active.
+        Get the value of a parameter over all years by accessing it
+        with an underscore in front of its name: ``pol._EITC_c`` instead of
+        ``pol.EITC_c``.
         """
         if (
             attr.startswith("_") and