fix small typos

murrayrm · murrayrm · commit e657edc0ecc6 · 2025-02-02T20:40:10.000-08:00
diff --git a/doc/develop.rst b/doc/develop.rst
@@ -83,7 +83,7 @@ GitHub repository file and directory layout:
 
         - \*.py, \*.rst - Python scripts (linked to ../examples/\*.py)
 
-        - \*.ipynb - Jupytern notebooks (linked to ../examples.ipynb)
+        - \*.ipynb - Jupyter notebooks (linked to ../examples.ipynb)
 
       + **figures/**
 
@@ -93,20 +93,23 @@ GitHub repository file and directory layout:
 
       + \*.py - Python scripts
 
-      + \*.ipynb - Jupytern notebooks
+      + \*.ipynb - Jupyter notebooks
 
 
 Naming conventions
 ==================
 
 Generally speaking, standard Python and NumPy naming conventions are
-used through the package.
+used throughout the package.
+
+* Python PEP 8 (code style): https://peps.python.org/pep-0008/
 
 
 Filenames
 ---------
 
-* Source files are lower case, usually less than 10 characters
+* Source files are lower case, usually less than 10 characters (and 8
+  or less is better).
 
 * Unit tests (in `control/tests/`) are of the form `module_test.py` or
   `module_function.py`.
@@ -116,40 +119,40 @@ Class names
 -----------
 
 * Most class names are in camel case, with long form descriptions of
-  the contents (`TimeResponseData`).
+  the object purpose/contents (`TimeResponseData`).
 
-* Input/output class names are written out as long as they aren't too
-  long (`StateSpace`, `TransferFunciton`), but for very long names
+* Input/output class names are written out in long form as they aren't
+  too long (`StateSpace`, `TransferFunction`), but for very long names
   'IO' can be used in place of 'InputOutput' (`NonlinearIOSystem`) and
   'IC' can be used in place of 'Interconnected' (`LinearICSystem`).
 
-* Some older classes don't follow these guidlines (e.g., `LTI` instead
-  of `LinearTimeInvariantSystem`).
+* Some older classes don't follow these guidelines (e.g., `LTI` instead
+  of `LinearTimeInvariantSystem` or `LTISystem`).
 
 
 Function names
 --------------
 
 * Function names are lower case with words separated by underscores.
 
-* Function names usuall describe what they do
+* Function names usually describe what they do
   (`create_statefbk_iosys`, `find_operating_points`) or what they
   generate (`input_output_response`, `find_operating_point`).
 
-* Some abbreviations and shorted versions are used when names get very
-  long (e.g., `create_statefbk_iosys` instead of
+* Some abbreviations and shortened versions are used when names get
+  very long (e.g., `create_statefbk_iosys` instead of
   `create_state_feedback_input_output_system`.
 
 * Factory functions for I/O systems use short names (partly from MATLAB
-  conventions, partly because they are pretty frequenctly used):
+  conventions, partly because they are pretty frequently used):
   `frd`, `flatsys`, `nlsys`, `ss`, and `tf`.
 
-* Short versions of common commands are created by creating an object
-  with the shorter name as a copy of the main object: `bode =
-  bode_plot`, `step = step_response`, etc.
+* Short versions of common commands with longer names are created by
+  creating an object with the shorter name as a copy of the main
+  object: `bode = bode_plot`, `step = step_response`, etc.
 
 * The MATLAB compatibility library (`control.matlab`) uses names that
-  line up with MATLAB (e.g., `lsim` instead of `forced_response`).
+  try to line up with MATLAB (e.g., `lsim` instead of `forced_response`).
 
 
 Parameter names
@@ -163,7 +166,7 @@ general patterns are emerging:
   `optimal.solve_ocp` (which probably should be named
   `optimal.`find_optimal_trajectory`...).
 
-System creating commands:
+System-creating commands:
 
 * Commands that create an I/O system should allow the use of the
   following standard parameters:
@@ -172,10 +175,16 @@ System creating commands:
 
   - `inputs`, `outputs`, `states`: number or names of inputs, outputs, state
 
-  These can be parsed in a consistent way using the
-  `iosys._process_iosys_keywords` function.
+  - `input_prefix`, `output_prefix`, `state_prefix`: change the default
+    prefixes used for naming signals.
 
-* Commands
+  - `dt`: set the timebase.  This one takes a bit of care, since if it
+    is not specified then it defaults to
+    `config.defaults['control.default_dt']`.  This is different than
+    setting `dt=None`, so you `dt` should always be part of **kwargs.
+
+  These keywords can be parsed in a consistent way using the
+  `iosys._process_iosys_keywords` function.
 
 System arguments:
 
@@ -185,8 +194,10 @@ System arguments:
   `interconnect`).  A single system should also be OK.
 
 * `sysdata` when an argument can either be a system, a list of
-  systems ,or data describing a response (e.g,
-  `nyquist_response`).
+  systems, or data describing a response (e.g, `nyquist_response`).
+
+  .. todo:: For a future release (v 0.11.x?) we should make this more
+            consistent across the package.
 
 Signal arguments:
 
@@ -206,6 +217,12 @@ can be incorporated into the User Guide.  All significant
 functionality should have a narrative description in the User Guide in
 addition to docstrings.
 
+Generally speaking, standard Python and NumPy documentation
+conventions are used throughout the package:
+
+* Python PEP 257 (docstrings): https://peps.python.org/pep-0257/
+* Numpydoc Style guide: https://numpydoc.readthedocs.io/en/latest/format.html
+
 
 General docstring info
 ----------------------
@@ -223,13 +240,13 @@ General docstring info
 Function docstrings
 -------------------
 
-Follow NumPyDoc format with the following additional detals:
+Follow numpydoc format with the following additional details:
 
 * All functions should have a short (< 64 character) summary line that
   starts with a capital letter and ends with a period.
 
-* All paramter descriptions should start with a capital letter and end
-  with a period.  An exception is paramters that have a list of
+* All parameter descriptions should start with a capital letter and end
+  with a period.  An exception is parameters that have a list of
   possible values, in which case a phrase sending in `:` followed by a
   list (without punctuation) is OK.
 
@@ -245,9 +262,9 @@ Follow NumPyDoc format with the following additional detals:
 Class docstrings
 ----------------
 
-Follow NumpyDoc format with the follow additional details:
+Follow numpydoc format with the follow additional details:
 
-* Paramaters used in creating an object go in the class docstring and
+* Parameters used in creating an object go in the class docstring and
   not in the `__init__` docstring (which is not included in the
   Sphinx-based documentation).  OK for the `__init__` function to have
   no docstring.
@@ -269,20 +286,42 @@ Follow NumpyDoc format with the follow additional details:
 I/O system classes:
 
 * Subclasses of `InputOutputSystem` should always have a factory
-  function that is used ot create them.  The class documentation only
-  needs to documen the required parameters; the full list of
+  function that is used to create them.  The class documentation only
+  needs to document the required parameters; the full list of
   parameters (and optional keywords) can and should be documented in
   the factory function docstring.
 
 
-Sphinx documentation:
+User Guide
+----------
+
+The purpose of the User Guide is provide a *narrative* description of
+the key functions of the package.  It is not expected to cover every
+command, but should allow someone who knows about control system
+design to get up and running quickly.
+
+The User Guide consists of chapters that are each their own separate
+`.rst` file and each of them generates a separate page.  Chapters are
+divided into sections whose names appear in the indexo on the left of
+the web page when that chapter is being viewed.  In some cases a
+section may be in its own file, including in the chapter page by using
+the `include` directive (see `nlsys.py` for an example).
+
+Sphinx files guidlines:
 
 * Each file should declare the `currentmodule` at or near the top of
-  the file.  Excpt for sub-packages (`control.flatsys`) and modules
-  that need to be impored separatly (`control.optimal`),
+  the file.  Except for sub-packages (`control.flatsys`) and modules
+  that need to be imported separately (`control.optimal`),
   `currentmodule` should be set to control.
 
 
+Reference Manual
+----------------
+
+The reference manual should provide a fairly comprehensive description
+of every class, function and configuration variable in the package.
+
+
 Utility functions
 =================
 
