djsundog/circuitpython
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Merge pull request #4678 from jposada202020/defining_parameters

Browse Source 
Defining parameters
This commit is contained in:
Dan Halbert 2021-05-03 09:22:09 -04:00 committed by GitHub
commit 4fafdf7e42
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 52 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
docs/design_guide.rst
View File

@ -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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^