Docstring formatting issues with numpydoc

[germa89]

Our doc strings are not very well formatted.

I'm getting lots of errors when using precommit with numpydoc. See #2381

So I'm forced to disable:

# Very important. They should be fixed asap.
"PR01", # "Parameters {missing_params} not documented",
"RT01", # "No Returns section found",
"PR02", # "Unknown parameters {unknown_params}",
 "RT03", # "Return value has no description",

# Not as important, but desirable
"GL02", # "Closing quotes should be placed in the line after the last text "
    # "in the docstring (do not close the quotes in the same line as "
    # "the text, or leave a blank line between the last text and the "
    # "quotes)",
"GL03", # "Double line break found; please use only one blank line to "
    # "separate sections or paragraphs, and do not leave blank lines "
    # "at the end of docstrings",
"SS03", # "Summary does not end with a period",
"PR09", # 'Parameter "{param_name}" description should finish with "."',
"RT05", # 'Return value description should finish with "."',
 "SS06", # "Summary should fit in a single line",
  "GL09", # "Deprecation warning should precede extended summary",
  "RT04", # "Return value description should start with a capital letter",
  "SS05", # "Summary must start with infinitive verb, not third person "
    # '(e.g. use "Generate" instead of "Generates")',
"PR08", # 'Parameter "{param_name}" description should start with a '

Ideally, we shall fix this in the future. Maybe this is a good work ChatGPT.

I'm aiming for the following configuration:

checks = [
    #"all",   # report on all checks, except the below
  # "GL01", # "Docstring text (summary) should start in the line immediately "
    # "after the opening quotes (not in the same line, or leaving a "
    # "blank line in between)",
    "GL02", # "Closing quotes should be placed in the line after the last text "
    # "in the docstring (do not close the quotes in the same line as "
    # "the text, or leave a blank line between the last text and the "
    # "quotes)",
    "GL03", # "Double line break found; please use only one blank line to "
    # "separate sections or paragraphs, and do not leave blank lines "
    # "at the end of docstrings",
    "GL05", # 'Tabs found at the start of line "{line_with_tabs}", please use '
    # "whitespace only",
  # "GL06", # 'Found unknown section "{section}". Allowed sections are: '
    # "{allowed_sections}",
    "GL07", # "Sections are in the wrong order. Correct order is: {correct_sections}",
  # "GL08", # "The object does not have a docstring",
    "GL09", # "Deprecation warning should precede extended summary",
    "GL10", # "reST directives {directives} must be followed by two colons",
    "SS01", # "No summary found (a short summary in a single line should be "
    # "present at the beginning of the docstring)",
    "SS02", # "Summary does not start with a capital letter",
    "SS03", # "Summary does not end with a period",
    "SS04", # "Summary contains heading whitespaces",
    "SS05", # "Summary must start with infinitive verb, not third person "
    # '(e.g. use "Generate" instead of "Generates")',
    "SS06", # "Summary should fit in a single line",
    "ES01", # "No extended summary found",
    "PR01", # "Parameters {missing_params} not documented",
    "PR02", # "Unknown parameters {unknown_params}",
    "PR03", # "Wrong parameters order. Actual: {actual_params}. "
    # "Documented: {documented_params}",
    "PR04", # 'Parameter "{param_name}" has no type',
    "PR05", # 'Parameter "{param_name}" type should not finish with "."',
    "PR06", # 'Parameter "{param_name}" type should use "{right_type}" instead '
    # 'of "{wrong_type}"',
    "PR07", # 'Parameter "{param_name}" has no description',
    "PR08", # 'Parameter "{param_name}" description should start with a '
    # "capital letter",
    "PR09", # 'Parameter "{param_name}" description should finish with "."',
    "PR10", # 'Parameter "{param_name}" requires a space before the colon '
    # "separating the parameter name and type",
    "RT01", # "No Returns section found",
  # "RT02", # "The first line of the Returns section should contain only the "
    # "type, unless multiple values are being returned",
    "RT03", # "Return value has no description",
    "RT04", # "Return value description should start with a capital letter",
    "RT05", # 'Return value description should finish with "."',
    "YD01", # "No Yields section found",
  # "SA01", # "See Also section not found",
    "SA02", # "Missing period at end of description for See Also "
    # '"{reference_name}" reference',
    "SA03", # "Description should be capitalized for See Also "
    # '"{reference_name}" reference',
    "SA04", # 'Missing description for See Also "{reference_name}" reference',
  # "EX01", # "No examples section found",
]

[germa89]

Pinging @clatapie for visibility.

[germa89]

This is going to be the perfect work for a cloudy low energy working day....

[germa89]

I had to disable GL07 because an issue with Pyvista docstrings in #2566

[germa89]

in #2759 I had to disable sphinx-autodoc-typehints because it was showing:

reading sources... [100%] mapdl_commands/solution/_autosummary/ansys.mapdl.core.Mapdl.svplot .. user_guide/xpl
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.Geometry.generate_surface:36: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.Geometry.get_elements_per_area:25: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.LegacyGeometry.keypoints:20: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.LegacyGeometry.lines:20: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/component.py:docstring of ansys.mapdl.core.component.ComponentManager.select:28: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/logging.py:docstring of ansys.mapdl.core.logging.Logger.add_instance_logger:41: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.Geometry.generate_surface:36: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/mapdl/core/mapdl_geometry.py:docstring of ansys.mapdl.core.mapdl_geometry.Geometry.get_elements_per_area:25: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/pyvista/plotting/themes.py:docstring of pyvista.plotting.themes._ThemeConfig.to_dict:24: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/tools/path/path.py:docstring of ansys.tools.path.path.change_default_ansys_path:20: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/tools/path/path.py:docstring of ansys.tools.path.path.find_ansys:20: WARNING: Explicit markup ends without a blank line; unexpected unindent.
/opt/hostedtoolcache/Python/3.10.13/x64/lib/python3.10/site-packages/ansys/tools/path/path.py:docstring of ansys.tools.path.path.save_ansys_path:20: WARNING: Explicit markup ends without a blank line; unexpected unindent.
looking for now-outdated files... none found