From 0c23c735102a4702f18adf6525a44ec563876034 Mon Sep 17 00:00:00 2001 From: jposada202020 Date: Wed, 28 Apr 2021 05:34:51 -0400 Subject: [PATCH 01/13] defining_parameters --- docs/design_guide.rst | 83 +++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 81 insertions(+), 2 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 1bac4df61b..9ff7dffb55 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -238,11 +238,34 @@ Module description After the license comment:: """ - `` - + `` ================================================= - + + + + * Author(s): + + Implementation Notes + -------------------- + + + **Hardware:** + + * Adafruit `Device Description + `_ (Product ID: ) + + **Software and Dependencies:** + + * Adafruit CircuitPython firmware for the supported boards: + https://circuitpython.org/downloads + * Adafruit's Bus Device library: + https://github.com/adafruit/Adafruit_CircuitPython_BusDevice + * Adafruit's Register library: + https://github.com/adafruit/Adafruit_CircuitPython_Register + """ + Class description ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -269,6 +292,54 @@ 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` + +Parameters Documentation +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +Although there are different ways to document class and functions definitions in Python, +the following is the prevalent method of doing paramaters documenations +for CircuitPython libraries. When documenting class parameters you should use the +following structure:: + + :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to + + +param_type +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Type of the parameter. This could be amon other ``int``, ``float``, ``str`` ``bool``, etc. +When referring to different objects in the CircuitPython domain you need to include the reference +by adding a `~` before the definition as shown in the following example:: + + :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 entry in the `conf.py` file located within the `docs` directory. +To add different types outside CircuitPython you need to add more definition to 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 inthersphinx_mapping above include reference to the 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 values, it is a good +practice to mention this:: + + :param int pitch: Pitch value for the servo. Defaults to :const:`4500` + + Attributes ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -383,6 +454,14 @@ Renders as: :param float degrees: Degrees to turn right +Documentation References to other Libraries +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +When you need to make references to documentation in other libraries you should refer the class using single +backticks ``:class:`~adafruit_motor.servo.Servo```. You must also add the reference in the ``conf.py`` file in the +``intersphinx_mapping section`` by adding a new entry:: + + "adafruit_motor": ("https://circuitpython.readthedocs.io/projects/motor/en/latest/", None,), + Use BusDevice -------------------------------------------------------------------------------- From 4e931697c6efee6db1188124a72adfa923c9d645 Mon Sep 17 00:00:00 2001 From: jposada202020 Date: Wed, 28 Apr 2021 06:07:45 -0400 Subject: [PATCH 02/13] adding_backticks, typos --- docs/design_guide.rst | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 9ff7dffb55..4c9ca00521 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -296,24 +296,28 @@ Renders as: Parameters Documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Although there are different ways to document class and functions definitions in Python, -the following is the prevalent method of doing paramaters documenations +the following is the prevalent method of doing parameters documentations for CircuitPython libraries. When documenting class parameters you should use the -following structure:: +following structure: - :param ~busio.I2C i2c_bus: The I2C bus the DS3231 is connected to +.. code-block:: sh + + :param param_type param_name: Parameter_description param_type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Type of the parameter. This could be amon other ``int``, ``float``, ``str`` ``bool``, etc. +Type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc. When referring to different objects in the CircuitPython domain you need to include the reference -by adding a `~` before the definition as shown in the following example:: +by adding 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 entry in the `conf.py` file located within the `docs` directory. +intersphinx_mapping entry in the ``conf.py`` file located within the ``docs`` directory. To add different types outside CircuitPython you need to add more definition to intersphinx_mapping:: From 3c49bd6bde1525558def647d0cca3d99ec9fb708 Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:09 -0400 Subject: [PATCH 03/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 4c9ca00521..814962c7c7 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -296,7 +296,7 @@ Renders as: Parameters Documentation ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Although there are different ways to document class and functions definitions in Python, -the following is the prevalent method of doing parameters documentations +the following is the prevalent method of documenting parameters for CircuitPython libraries. When documenting class parameters you should use the following structure: From 69a510edc1b24634e7fd24ae330a1d05d9e08019 Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:17 -0400 Subject: [PATCH 04/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 814962c7c7..7eecc4fe87 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -308,8 +308,8 @@ following structure: param_type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc. -When referring to different objects in the CircuitPython domain you need to include the reference -by adding a ``~`` before the definition as shown in the following example: +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 From 9fe1751f0195dc705e818322e24a841bf5bd7685 Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:28 -0400 Subject: [PATCH 05/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 7eecc4fe87..81975a2117 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -316,7 +316,7 @@ definition as shown in the following example: :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 +To include references to CircuitPython modules, cookiecutter creates an entry in the intersphinx_mapping entry in the ``conf.py`` file located within the ``docs`` directory. To add different types outside CircuitPython you need to add more definition to intersphinx_mapping:: From 129df1b3f78c62b349cd63a24726d78fae955e9c Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:37 -0400 Subject: [PATCH 06/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 81975a2117..2a5a24d56e 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -317,7 +317,7 @@ definition as shown in the following example: To include references to CircuitPython modules, cookiecutter creates an entry in the -intersphinx_mapping entry in the ``conf.py`` file located within the ``docs`` directory. +intersphinx_mapping section in the ``conf.py`` file located within the ``docs`` directory. To add different types outside CircuitPython you need to add more definition to intersphinx_mapping:: From aa9114254aa3cee6a385a6acf72efd4d200b80c3 Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:45 -0400 Subject: [PATCH 07/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 2a5a24d56e..9da43be431 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -327,7 +327,7 @@ To add different types outside CircuitPython you need to add more definition to "CircuitPython": ("https://circuitpython.readthedocs.io/en/latest/", None), } -The inthersphinx_mapping above include reference to the Python, BusDevice and CircuitPython +The intersphinx_mapping above includes references to Python, BusDevice and CircuitPython Documentation From 1950cf66664c1ab83fe226d9907b5cad7bf35a0f Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:15:55 -0400 Subject: [PATCH 08/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 9da43be431..6ced1b4e17 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -338,7 +338,7 @@ Parameter name used in the class or method definition Parameter_description ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Parameter description. When the parameter defaults to a particular values, it is a good +Parameter description. When the parameter defaults to a particular value, it is good practice to mention this:: :param int pitch: Pitch value for the servo. Defaults to :const:`4500` From ed2980b967768018144e784895b923152124ed5e Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:16:02 -0400 Subject: [PATCH 09/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 6ced1b4e17..7df3c40b95 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -460,7 +460,7 @@ Renders as: Documentation References to other Libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -When you need to make references to documentation in other libraries you should refer the class using single +When you need to reference documentation in other libraries you should include the class by using single backticks ``:class:`~adafruit_motor.servo.Servo```. You must also add the reference in the ``conf.py`` file in the ``intersphinx_mapping section`` by adding a new entry:: From 8ff29f68db41017e1f16d27468f5ba3d202f16fd Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:16:11 -0400 Subject: [PATCH 10/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 7df3c40b95..c639be902f 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -307,7 +307,7 @@ following structure: param_type ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Type of the parameter. This could be among other `int`, `float`, `str` `bool`, etc. +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: From e33bc9f57be32317cdc078e220359c243642dddb Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:16:21 -0400 Subject: [PATCH 11/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index c639be902f..e1e5b83635 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -339,7 +339,7 @@ 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 mention this:: +practice to include the default:: :param int pitch: Pitch value for the servo. Defaults to :const:`4500` From 71d575f0c4e0b57fa4a2e16b991461f9fb5df526 Mon Sep 17 00:00:00 2001 From: jposada202020 <34255413+jposada202020@users.noreply.github.com> Date: Wed, 28 Apr 2021 13:16:33 -0400 Subject: [PATCH 12/13] Update docs/design_guide.rst Co-authored-by: Kattni --- docs/design_guide.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index e1e5b83635..630203ff5f 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -318,7 +318,7 @@ definition as shown in the following example: 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 add more definition to intersphinx_mapping:: +To add different types outside CircuitPython you need to include them in the intersphinx_mapping:: intersphinx_mapping = { From 9c12b180c843d76067bb5b6471c572bea280a379 Mon Sep 17 00:00:00 2001 From: jposada202020 Date: Wed, 28 Apr 2021 13:21:18 -0400 Subject: [PATCH 13/13] title change --- docs/design_guide.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/design_guide.rst b/docs/design_guide.rst index 630203ff5f..a0db2df79f 100644 --- a/docs/design_guide.rst +++ b/docs/design_guide.rst @@ -293,7 +293,7 @@ Renders as: :param int address: The I2C address of the device. Defaults to :const:`0x40` -Parameters Documentation +Documenting Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Although there are different ways to document class and functions definitions in Python, the following is the prevalent method of documenting parameters @@ -308,7 +308,7 @@ following structure: 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 +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