Merge pull request #4678 from jposada202020/defining_parameters

Defining parameters

Author: dhalbert

docs/design_guide.rst

@@ -292,6 +292,58 @@ Renders as:
     :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
     :param int address: The I2C address of the device. Defaults to :const:`0x40`
 
+
+Documenting Parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Although there are different ways to document class and functions definitions in Python,
+the following is the prevalent method of documenting parameters
+for CircuitPython libraries. When documenting class parameters you should use the
+following structure:
+
+.. code-block:: sh
+
+    :param param_type param_name: Parameter_description
+
+
+param_type
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc.
+To document an object in the CircuitPython domain, you need to include a ``~`` before the
+definition as shown in the following example:
+
+.. code-block:: sh
+
+    :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to.
+
+
+To include references to CircuitPython modules, cookiecutter creates an entry in the
+intersphinx_mapping section in the ``conf.py`` file located within the ``docs`` directory.
+To add different types outside CircuitPython you need to include them in the intersphinx_mapping::
+
+
+    intersphinx_mapping = {
+        "python": ("https://docs.python.org/3.4", None),
+        "BusDevice":("https://circuitpython.readthedocs.io/projects/busdevice/en/latest/", None,),
+        "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None),
+    }
+
+The intersphinx_mapping above includes references to Python, BusDevice and CircuitPython
+Documentation
+
+
+param_name
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Parameter name used in the class or method definition
+
+
+Parameter_description
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Parameter description. When the parameter defaults to a particular value, it is good
+practice to include the default::
+
+    :param int pitch: Pitch value for the servo. Defaults to :const:`4500`
+
+
 Attributes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^