Whitespace change in autogenerated CONFIG docstrings causes Sphinx warnings

[lbianchi-lbl]

Observed in watertap-org/watertap#1032 as part of the process to update dependencies from IDAES 2.0.0/Pyomo 6.5.0:

The generated warning (one of many, relative to the class shown in the screenshot above) from this ReadTheDocs build log:

/home/docs/checkouts/readthedocs.org/user_builds/watertap/checkouts/1034/watertap/property_models/cryst_prop_pack.py:docstring of watertap.property_models.cryst_prop_pack.NaClParameterBlock:1: WARNING: Block quote ends without a blank line; unexpected unindent.

This causes the build to fail if the Sphinx -W/fail-on-warning setting is enabled.

[lbianchi-lbl]

• From a uninformed quick look at the diff between Pyomo 6.5.0 and 6.5.1, this looks like it could be related to changes in pyomo.common.formatting and specifically the introduction of wrap_reStructuredText():

  IDAES/pyomo@6.5.0...6.5.1.idaes.2023.03.28#diff-1a2731acd796fdfba1065e27dd88538672d8cf61464e62a0a1022cce240c7b80R269

• As far as I can tell this was introduced in Improve formatting of docstrings generated from ConfigDict Pyomo/pyomo#2754

• The corresponding IDAES PR is Update approach for documenting Config Blocks #1148

[andrewlee94]

@jsiirola Any suggestion on this? Is it something that is in the IDAES usage of the Pyomo documentation functions (e.g. something we need to add to include the trailing linebreak), a difference in the Pyomo tool output, or a bad habit that Pyomo is now being more vocal about?

[lbianchi-lbl]

@jsiirola Any suggestion on this? Is it something that is in the IDAES usage of the Pyomo documentation functions (e.g. something we need to add to include the trailing linebreak), a difference in the Pyomo tool output, or a bad habit that Pyomo is now being more vocal about?

I've just tried using https://pypi.org/project/rstcheck/, and it seems to confirm that the IDAES 2.0.0/Pyomo 6.5.0 output is valid, while the IDAES/idaes-pse@main/Pyomo 6.5.1 is not:

conda create --yes test-idaes-1191 python=3.10 && conda activate test-idaes-1191
pip install "watertap @ git+https://github.com/watertap-org/watertap@main" rstcheck
pip show pyomo idaes-pse
pip uninstall --yes pyomo idaes-pse && pip install idaes-pse==2.0.0 pyomo=6.5.0 && pip show pyomo idaes-pse
python -c 'from watertap.property_models.cryst_prop_pack import NaClParameterBlock as obj; print(obj.__doc__)' | rstcheck -
# output: Success! No issues detected.
pip uninstall --yes pyomo idaes-pse && pip install "idaes-pse @ git+https://github.com/IDAES/idaes-pse@main" && pip show pyomo idaes-pse
python -c 'from watertap.property_models.cryst_prop_pack import NaClParameterBlock as obj; print(obj.__doc__)' | rstcheck -
# output: <stdin>:17: (WARNING/2) Block quote ends without a blank line; unexpected unindent. Error! Issues detected.

[jsiirola]

I looked into this and Pyomo/pyomo#2853 restores (most of) the old behavior. However, relying on the indentation in the ConfigDict declarations to generate correct RST is fragile at best. This is exactly why Pyomo introduced the use of wrap_reStructuredText() in the numpydoc formatter [it also automatically documents types and defaults] (which IDAES is NOT using).

Given that the bulk of IDAES docstrings have settled on google-style doc strings, we should probably look into making a google-style formatter that we use in IDAES.

[lbianchi-lbl]

This specific issue (i.e. the backward-incompatible change) has been addressed by Pyomo/pyomo#2853, so this can be closed. #1196 is to discuss more long-term solutions related to the general autogenerated docstring functionality.