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 theupdated 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 themake doctest command in thedoc/ directory (called automatically whenmake html is run).
• Regularized the way that classes, functions, methods, parameters, built-ins, and code samples are annotated and created acustom.css file to control HTML formatting:
  • Classes, functions, methods, and parameters use single backticks, with no additional directives, and are treated using thepy: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 theControl 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 chapterPackage Configuration Parameters to the Reference Manual, with documentation on everything available viact.config.defaults (and a unit test to make sure nothing is missing).
• Added a new chapterDeveloper 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 andtemplate.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.
• Addednumpydoc checks incontrol/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 todoc/examples and documentation figures todoc/figures to declutter thedoc 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 indoc/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 inexamples/template.py.
• Removed top-level class dependence onobject
• Removed (unused) table inmatlab/__init__ and replaced withdoc/matlab.rst (part of Reference Manual)
• Ranisort -m2 on all files to sort imports.
• Improved consistency checking incontrol/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:

• Renamedacker toplace_acker (to be consistent withplace_varga) and setacker = place_acker.
• Identified source code lines that were more than 79 characters and reformatted (PEP 8).
• [25 Jan 2025] TheNamedSignal class now has a__repr__ method that evaluates back to aNamedSignal (similar to theInputOutputSystem__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