This (very large) PR contains a restructuring of the Sphinx documentation, including changes to improve uniformity of docstrings along with draft guidelines for developers. This is being posted initially as a draft PR so that people can start to have a look at the changes and provide feedback.

High level principles:

• No documentation has been removed, only shifted around.
• With a few small exceptions, to fix up inconsistencies, there are no changes to the code base and all previous code will run without change.

Because of the large number of files changed, this PR will probably be very difficult to review based on looking at the changes to individual files. It will probably make more sense to look through the updated version of the documentation on ReadTheDocs.

Summary of significant changes:

• Sphinx documentation is now divided into a User Guide, which provides a narrative style description of python-control package, and a Reference Manual, which has a listing of all functions, classes, package configuraton parameters, and other detailed information about the package.
• Control plots included in the documentation are generated by the code in the documentation, using the Sphinx doctest extension. Figures are created using the make doctest command in the doc/ directory (called automatically when make html is run).
• Regularized the way that classes, functions, methods, parameters, built-ins, and code samples are annotated and created a custom.css file to control HTML formatting:
  • Classes, functions, methods, and parameters use single backticks, with no additional directives, and are treated using the py:obj directive. For classes, functions, and methods, this will generate a link using bold, code font. For parameters, non-bold text is used (since Sphinx does not yet support links to parameter documentation).
  • Code samples use double backticks and are rendered in non-bold, black, fixed width font (versus the default red color).
  • Python built-ins (True, False, None) are written with no backticks. This was previously very non-uniform, and this style fits what is commonly used in the NumPy documentation.
• Moved the Control Systems Classes chapter to the Reference Manual and added all classes in the package (previous it was just the I/O system classes).
• Added a new chapter Package Configuration Parameters to the Reference Manual, with documentation on everything available via ct.config.defaults (and a unit test to make sure nothing is missing).
• Added a new chapter Developer Notes to the reference manual that describes the various choices that were made in making the package structure and documentation uniform. Sections in the chapter:
  • Package Structure: how the package is organized (directories, files)
  • Naming Conventions: how to name files, classes, functions, etc
  • Documentation Guidelines: how to document various types of objects, including consistent use of backticks (with rationale), as well a description of what goes in the User Guide vs Reference Manual chapters.
  • Utility Functions: a relatively incomplete listing of some of the more common utility functions for developers.
  • Sample Files: template.py and template.rst that implement the guidelines.
• Got rid of docstring hashes for functions with variable arguments and instead used docstring signatures as a replacement for checking that parameters are documented.
• Added numpydoc checks in control/tests/docstring_test.py to pick up things like improperly labeled sections (e.g., "See also" instead of "See Also") and other errors.
• Moved documentation from __init__ docstrings (which is not included in the Sphinx documentation) to class documentation (with details in the factory function, when appropriate).
• Moved documentation examples files to doc/examples and documentation figures to doc/figures to declutter the doc directory (this accounts for many of the 226 files that have changed).
• [26 Jan 2025] Added Release Notes providing a (user-oriented) summary of changes in recent releases (with a summary of earlier releases). Release notes are contained in doc/releases.

Smaller changes:

• Added Sphinx unit test (doc/test_sphinx) to make sure all primary functions are documented in the Reference Manual.
• Updated file header information to be a standard form, shown in examples/template.py.
• Removed top-level class dependence on object
• Removed (unused) table in matlab/__init__ and replaced with doc/matlab.rst (part of Reference Manual)
• Ran isort -m2 on all files to sort imports.
• Improved consistency checking in control/tests/docstring_test.py unit test checks:
  • All function and parameter summaries now start with a capital letter and end with a period.
  • Added checking docstring format of "Returns" section, in addition to "Parameters".
• Remove excess spaces throughout the package (since all files were touched).
• Equations are now centered in Sphinx, instead of left justified.

Small code changes:

• Renamed acker to place_acker (to be consistent with place_varga) and set acker = place_acker.
• Identified source code lines that were more than 79 characters and reformatted (PEP 8).
• [25 Jan 2025] The NamedSignal class now has a __repr__ method that evaluates back to a NamedSignal (similar to the InputOutputSystem __repr__ method).

Additional changes that are coming:

• Regularize frequency response arguments/return vals: (fresp, freqpts)
• Regularize timebase documentation ('dt' format + wording)
• Make sure all MATLAB functions are documented in Reference Manual
• Get rid of numbered notes (just use paragraphs)
• Remove all remaining .. todo::'s
• Fix additional typos and grammatical inconsistencies