Reduce Sphinx documentation build warnings (#800)

* Removing a lot of warnings when building docs

* Loosening ammonia tolerance in the example test

* Cleaning up a few more docs build issues

* Fixing minor doc indentation issues

Author: johnjasa

CHANGELOG.md

@@ -50,6 +50,17 @@
 - Removed hard-coded logic of price units in finance models to be flexible to any type of commodity. Created helper functions `_compute_price_units` and `_compute_rate_units` in `h2integrate.finances.tools` and integrated usage of these functions into all finance models  (`numpy_financial_npv`, `profast_npv`, `profast_lco`) accordingly. [PR 786](https://github.com/NatLabRockies/H2Integrate/pull/786)
 - Removed the `is_electricity_producer` helper from `h2integrate.core.commodity_stream_definitions` and the electricity-specific auto-detection branch in `H2IntegrateModel`, making finance-subgroup `commodity_stream` resolution fully commodity-agnostic; updated example `plant_config.yaml` files that previously relied on the auto-detection to set `commodity_stream` explicitly. [PR 786](https://github.com/NatLabRockies/H2Integrate/pull/786)
 - Ensure OpenMDAO data is cleaned up during testing [PR 797](https://github.com/NatLabRockies/H2Integrate/pull/797).
+- Added capability to specify demand technology for system-level control, and renamed the framework-derived system-level control classification dict from `slc_config` to `slc_topology` to distinguish it from the user-authored `control_parameters` block. [PR 784](https://github.com/NatLabRockies/H2Integrate/pull/784)
+- Reduced Sphinx documentation build warnings from roughly 880 to under 20. [PR 800](https://github.com/NatLabRockies/H2Integrate/pull/800)
+  - Set `napoleon_use_ivar` and added `napoleon_custom_sections` so custom Google-style sections (Inputs, Outputs, Promoted Inputs, Promoted Outputs, Subsystems, Discrete Inputs, Discrete Outputs, Options, Behavior, Side Effects) render cleanly.
+  - Suppressed the `etoc.toctree` category emitted by autosummary `:recursive:` stubs.
+  - Cleared stale `_autosummary/` files at the start of every docs build.
+  - Removed duplicated `Methods:` docstring sections that collided with autodoc method discovery.
+  - Added `:no-index:` to hand-authored autoclass directives that duplicated autosummary entries.
+  - Cleaned up docstring formatting bugs across roughly twenty source files (bullet and definition list separations, starred attribute markers, unbalanced backticks, and stray substitution references).
+  - Fixed several MyST cross-reference targets (missing labels, ambiguous doc vs ref targets, incorrect autosummary path, duplicate labels, broken image path, and a broken literalinclude path).
+  - Added a custom `docs/_templates/autosummary/module.rst` template that filters pytest `conftest.py` submodules from generated stubs, eliminating the "failed to import conftest" warnings that appeared on the Read the Docs build.
+  - Renamed the `GeoH2SubsurfaceCostModel` MyST label in `docs/technology_models/geologic_hydrogen.md` to `mathur-modified-geoh2-cost` to remove an ambiguous cross-reference with the autosummary entry for the Python class of the same name.
 - Updates `h2integrate/core/file_utils.py::check_data_dir` to allow for the creation of nested
   directories, not just the final subdirectory for smoother initialization of a feedstock directory
   [PR 801](https://github.com/NatLabRockies/H2Integrate/pull/801).

docs/_config.yml

@@ -61,7 +61,41 @@ sphinx:
     autodoc_typehints: description
     html_static_path:
       - _static
+    # A local ``autosummary/module.rst`` template lives here that filters out
+    # pytest ``conftest.py`` submodules from the generated stubs (they can't be
+    # imported outside a pytest session, so autosummary would emit "failed to
+    # import" warnings for every one).
+    templates_path:
+      - _templates
     napoleon_use_admonition_for_notes: true
     napoleon_use_rtype: false
+    # Render "Attributes:" sections with the :ivar: role instead of separate
+    # ".. attribute::" directives. This prevents autodoc from documenting the
+    # same attribute twice (once from the napoleon-parsed Attributes: block and
+    # once from autodoc's own member discovery), which was the single largest
+    # source of "duplicate object description" warnings in the docs build.
+    napoleon_use_ivar: true
+    # Teach napoleon about extra Google-style section headings that appear in
+    # H2Integrate docstrings. Each entry is either a plain string (renders as
+    # a generic section) or a ``[name, style]`` pair mapping the section to
+    # an existing napoleon style so its contents are parsed as parameters.
+    napoleon_custom_sections:
+      - [Inputs, params_style]
+      - [Outputs, params_style]
+      - [Promoted Inputs, params_style]
+      - [Promoted Outputs, params_style]
+      - [Subsystems, params_style]
+      - [Discrete Inputs, params_style]
+      - [Discrete Outputs, params_style]
+      - [Options, params_style]
+      - [Behavior, notes_style]
+      - [Side Effects, notes_style]
+    # Suppress the class of warnings emitted by sphinx-external-toc for
+    # ``.. toctree::`` directives inside autosummary-generated stubs. Those
+    # toctrees are how ``autosummary :recursive:`` links its child module
+    # pages together and can't be moved into ``_toc.yml``, so the warnings
+    # are noise rather than a real problem to fix.
+    suppress_warnings:
+      - etoc.toctree
     nb_merge_streams: true
     nb_execution_raise_on_error: true

docs/_templates/autosummary/module.rst

@@ -0,0 +1,65 @@
+{{ fullname | escape | underline}}
+
+.. automodule:: {{ fullname }}
+
+   {% block attributes %}
+   {% if attributes %}
+   .. rubric:: {{ _('Module Attributes') }}
+
+   .. autosummary::
+   {% for item in attributes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block functions %}
+   {% if functions %}
+   .. rubric:: {{ _('Functions') }}
+
+   .. autosummary::
+   {% for item in functions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block classes %}
+   {% if classes %}
+   .. rubric:: {{ _('Classes') }}
+
+   .. autosummary::
+   {% for item in classes %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+   {% block exceptions %}
+   {% if exceptions %}
+   .. rubric:: {{ _('Exceptions') }}
+
+   .. autosummary::
+   {% for item in exceptions %}
+      {{ item }}
+   {%- endfor %}
+   {% endif %}
+   {% endblock %}
+
+{% block modules %}
+{# Filter out pytest conftest modules; they cannot be imported outside a
+   pytest session (they use `from test.conftest import ...` which requires
+   the repo-root ``test/`` package to be on ``sys.path``) and so autosummary
+   raises "failed to import" warnings on them. #}
+{% set filtered_modules = modules | reject('equalto', 'conftest') | list %}
+{% if filtered_modules %}
+.. rubric:: Modules
+
+.. autosummary::
+   :toctree:
+   :recursive:
+{% for item in filtered_modules %}
+   {{ item }}
+{%- endfor %}
+{% endif %}
+{% endblock %}

docs/build_book.sh

@@ -18,6 +18,13 @@ if [[ "${1:-}" == "--clean" ]]; then
     rm -rf _build
 fi
 
+# Always remove the autosummary-generated stubs before building. These files
+# are regenerated from the current package layout by ``autosummary_generate``,
+# but sphinx does not delete stubs for modules that were renamed or removed.
+# Leaving stale stubs behind produces spurious "failed to import" /
+# "document isn't included in any toctree" warnings on every subsequent build.
+rm -rf _autosummary
+
 # Generate the interactive class hierarchy diagram
 python generate_class_hierarchy.py
 

docs/control/system_level_control/control_classifier.md

@@ -19,7 +19,7 @@ storage | Can modulate consumption/production within bounds while tracking SOC |
 feedstock | Are not directly controlled, but useful for SLC to make dispatch decisions | feedstocks
 
 To add a classifier for a particular model it would look something like this in the class:
-```{python}
+```python
 _control_classifier = "flexible"
 ```
 
@@ -30,14 +30,15 @@ _control_classifier = "flexible"
 ## Fixed
 A fixed performance model represents anything that always produces at its rated capacity and cannot be controlled or reduced by the system level controller. The SLC reads the output from a fixed technology and subtracts it from the demand, but does not send a set-point back to the technology. A good example of this is a classical nuclear plant model: it produces a constant output that the rest of the system must accommodate.
 
+(flexible)=
 ## Flexible
 A flexible performance model represents anything whose production is determined by an external resource (e.g., wind speed, solar irradiance) and that can only be *reduced* below that resource-determined maximum and never increased above it. The system-level controller sends a `{commodity}_set_point` that acts as an upper bound: when the resource-driven output exceeds the set-point, output is curtailed down to the set-point; otherwise, output is left at the resource-driven value. A good example is the PVWatts PySAM solar plant in H2I; its performance is a function of the input solar resource, and we cannot tell the sun to shine more, but we can curtail the panel output below the available solar production.
 
 In other words, flexible is a strictly more restricted case of [dispatchable](#dispatchable): a dispatchable model can be ramped both up and down in response to a set-point, while a flexible model can only be ramped down.
 
 To simplify the implementation of applying this curtailment we added a method, `apply_curtailment()`, to the `PerformanceBaseClass`.
 
-```{figure} figures/curtailable.png
+```{figure} figures/flexible.png
 :width: 70%
 :align: center
 ```

docs/control/technology_level_control/open-loop_controllers.md

@@ -108,4 +108,4 @@ An example output for the first week of a one-year simulation is shown below. Or
 For an example of how to use the `PeakLoadManagementHeuristicOpenLoopStorageController`, see:
 - `examples/33_peak_load_management/`
 
-For API details, see the [`PeakLoadManagementHeuristicOpenLoopStorageController` API documentation](../_autosummary/h2integrate.control.control_strategies.storage.plm_openloop_storage_controller).
+For API details, see the [`PeakLoadManagementHeuristicOpenLoopStorageController` API documentation](../../_autosummary/h2integrate.control.control_strategies.storage.plm_openloop_storage_controller).

docs/developer_guide/adding_a_new_technology.md

@@ -12,11 +12,11 @@ Every model in H2Integrate inherits from a small set of baseclasses that wire it
 into the rest of the framework. Before writing code, pick the appropriate base
 class and configuration class for each piece of your technology.
 
-See the class structure in H2I to learn more: [Class Structure](#class_structure)
+See the class structure in H2I to learn more: {ref}`Class Structure <class_structure>`
 
 ## Adding a new technology
 
-Common model types (performance, cost, control, etc.) with slightly more explanation and examples are include here: [Technology Model Types](#technology_model_types)
+Common model types (performance, cost, control, etc.) with slightly more explanation and examples are include here: {ref}`Technology Model Types <technology_model_types>`
 
 Every model has:
 - [Required class attributes](#required-class-attributes): These are usually defined within the class but not in a specific function definition.
@@ -103,9 +103,9 @@ class SolarPerformanceClass(PerformanceModelBaseClass):
         )
 
     def compute(self, inputs, outputs, discrete_inputs, discrete_outputs):
-        # example calculation using inputs set in `setup()
+        # example calculation using inputs set in setup()
         # this input can be an openmdao design variable
-        rated_pv_output = inputs["system_capacity"]*0.33 `
+        rated_pv_output = inputs["system_capacity"] * 0.33
 
         # example of calculation using a value from the attrs configuration class.
         # this method of input cannot be an openmdao design variable
@@ -116,10 +116,10 @@ class SolarPerformanceClass(PerformanceModelBaseClass):
 
         ...
 
-        # set outputs defined in `setup()` or baseclass `setup()`
+        # set outputs defined in setup() or baseclass setup()
         output["panel_efficiency"] = panel_efficiency
 
-        # this output is defined in the `PerformanceModelBaseClass` but is required to be set in the performance model since that class is inherited
+        # this output is defined in the PerformanceModelBaseClass but is required to be set in the performance model since that class is inherited
         output["capacity_factor"] = capacity_factor
 
 ```

docs/developer_guide/testing.md

@@ -62,7 +62,7 @@ Run `pytest -m unit` to run only the unit test suite or `pytest -m not-unit` to
 An example of a unit test is in the example below where there is only a validation of the location
 of the output directory and subdirectory, and not the contents of those files.
 
-:::{literalinclude} ../../h2integrate/resource/utilities/test/test_resource_file_tools.py
+:::{literalinclude} ../../h2integrate/core/test/test_utilities.py
 :start-at: @pytest.mark.unit
 :end-at: assert output_dir == expected_output_dir
 :::

docs/resource/resource_index.md

@@ -14,6 +14,7 @@ There are two ways to supply resource data to a technology:
 
 
 
+(resource-data-specified-using-setval)=
 ### Resource data specified using `set_val()`
 
 Resource data for a technology can be set using the `set_val()` command. In the [Run of River Example](https://github.com/NatLabRockies/H2Integrate/tree/develop/examples/07_run_of_river_plant/), the technology named `river` needs a resource input called `discharge`. An example of this is shown below:
@@ -38,6 +39,7 @@ h2i.run()
 ```
 
 
+(custom-resource-models)=
 ### Custom resource models
 The benefit of using a custom resource model is that the resource data can be made to vary for different inputs, which can be beneficial if running a design sweep or optimization where the resource location (specified by a latitude and longitude) is a design variable.
 

docs/resource/solar_index.md

@@ -1,4 +1,5 @@
 (solar_resource:models)=
+(solar-resource-model-overview)=
 # Solar Resource: Model Overview
 
 - [GOES PSM v4 API](goes_solar_v4_api): these models require an API key from the [NLR developer network](https://developer.nlr.gov/signup/), the available models are:
@@ -20,6 +21,7 @@ Please refer to the [Setting Environment Variables](../getting_started/environme
 ```
 
 (solarresource:overview)=
+(solar-resource-output-data)=
 # Solar Resource: Output Data
 
 Solar resource models may output solar resource data, site information, information about the data source, and time information. This information is outputted as a dictionary. The following sections detail the naming convention for the dictionary keys, standardized units, and descriptions of all the output data that may be output from a solar resource model.