Scarabaeus External Resource Guide#
Last revised by Z. Ellis on 2025 MAR 11
Introduction#
The external resource, where you are now, consists of two separate kinds of information:
Auto-Generated Script Documents in the Library Reference
Custom Non-Script Articles
In addition to the coding conventions we explored in the previous section, it’s also important that we provide information to populate Scarabaeus’ external resource. We do this by automatically generating documentation for every class and method in Scarabaeus. Thhis document explains the steps necessary for ensuring that auto-generated documentation builds and renders correctly by providing generalized standards and formatting rules when writing a class or methods for Scarabaeus.
The file TemplateClass.py has been set up as an extra example to follow as well. It is available in its entirety within Scarabaeus under
docs/TemplateClass.py, or here in the documentation.
For details on how to create an article that is not generated from a script, articles like this one, see LINK.
Documenting Scripts for the Library Reference#
This entire documentation resource is generated using Sphinx. The bulk of the information we must provide to Sphinx is given in the form of multiple docstrings throughout the file. These docstrings must follow a specific format to ensure cohesion throughout the resource. This format follows a modified version of Numpy’s dev manual. There are three types of docstring that each serve different purposes in creating a comprehensive resource for a Scarabaeus class:
Class Docstring - the main source of information for a Scarabaeus class.
Property Docstrings - supplementary information for the Class Docstring detailing class properties.
Method Docstrings - information describing the use of a method.
In the following sections we will walk through the formatting as well as the purpose of each of these types. These sections will provide references for formatting these docstrings. They are interpreted by Sphinx using the .rst format. For a helpful list of formatting rules in .rst, see this cheat sheet. Addtionally, if you would like to include tables in your documentation, this generator set to “Text” makes it much easier to do so.
Note
Many times, docstrings can become very large and make reading the code itself difficult. Remember that in VSCode, all docstrings can be collapsed by clicking the down arrow beside the line number of the first """.
General Docstring Rules#
Before we talk about the different kinds of docstrings, we should first note a few general rules that apply to all of them. These are meant to guide you in writing informative documentation while maintaining a general style throughout.
Writing Descriptions#
In general, descriptions should be as informative as possible. There will always be some prior knowledge expected of the user, but try to remember that most people won’t take the time to read through every line of the source code. Make sure that your explanations don’t leave any ambiguity.
Additionally, as a stylistic note, when writing a description, try not to use phrases like “this class” or “this method”. These tend to be superfluos and make the documentation more bloated than it needs to be. For example, instead of “this method generates xyz”, consider simply “generates xyz”. It’s a small detail, but following this guideline will help make your writing more succint as well as maintain a consistent style across the documentation.
Many times our variable or method names include abbreviations. The documentation gives us an opportunity to give context to these abbreviations. For example, if we have
the property STM0, when we give it a property description we should note the full name like:
@property
def STM0(self) -> dict:
"""
Initial state transition matrix (STM).
"""
Finally, for writing descriptions, there are a few oddities that come with how Sphinx reads in our documentation:
When using math formatting, make sure to use double “" to denote a command. It will not work otherwise.
To denote in-line code, make sure to use double back ticks “``”. It will not render as in-line otherwise.
Descriptions should end with periods.
Type-hinting numpy arrays in the docstring require the full name:
numpy.ndarray.
Defining ArrayWUnits#
When documenting ArrayWUnits objects, make sure to include their recommended units as well. If there are no recommended units, include the dimensions instead.
To ensure a consistent style throughout the resource, be sure to follow the structure “<definition>. <units specification>.” For fractional units,
use the :math: directive. See the example Class Docstring (see sections below):
"""
Parameters
----------
awu_input : ArrayWUnits
The AWU being documented. Recommend expressed in units of :math:`\\frac{km}{s^2}`.
"""
The description will render as:
“The AWU being documented. Recommend expressed in units of \(\\frac{km}{s^2}\).”
For none-compound units, spell them out instead:
"""
The AWU being documented. Expressed in units of Newtons.
:base: TemplateClass
:type: ArrayWUnits
"""
Notice that in this example we’re defining an ArrayWUnits in a Property Docstring (see sections below) instead of a Class Docstring like the previous example. This “<definition>. <units specification>.” applies anywhere we might need to define an ArrayWUnits object.
Since AWU’s can hold vectorial and matrix infomration, it’s also important for us to note the size and shape if it isn’t a scalar value. This combined with our unit specification gives us an example like:
"""
Parameters
----------
position : ArrayWUnits
3x1 vector describing the spacecraft's position. Expressed in units of kilometers.
"""
Class Docstring#
The first and most important docstring type is the Class Docstring. It is placed directly below the class definition in the code and consists of anywhere from two to seven different subsections, depending on the complexity of the class and the relevance of the subsections. Some of these subsections are mandatory and others are discretionary, denoted in the list below:
The Class Description - mandatory
The Parameters Section - mandatory
The Raises Section - at discretion
The See Also Section - at discretion, recommended
The Notes Section - at discretion, recommended
The References Section - at discretion
The Examples Section - at discretion, recommended
All of these sections are placed within the same docstring, book-ended by two sets of three quotation marks. All of the contents should be indented once inwards. It will take the below form (this is a helpful copy-paste template), with the following sections providing more detail:
"""
CLASS DESCRIPTION
Parameters
----------
arg : type
DESC
arg_two : type or other_type, optional
DESC. Defaults to ``default_value``.
Raises
------
REMOVE IF NO SPECIAL ERRORS
See Also
--------
REMOVE IF NO SEE ALSOS
Notes
-----
REMOVE IF NO NOTES
References
----------
REMOVE IF NO REFERENCES
Examples
--------
.. code-block:: python
# initial setup
import scarabaeus as scb
"""
The Class Description#
The first section of the Class Docstring is the Class Description, which, as its name suggests, provides information about the class. This is a mandatory inclusion in the Class Docstring, so make sure you’ve filled it out during your documentation process.
"""
Here you should provide a sentence or two concisely explaining the class and its
functions.
If necessary, you can provide a longer explanation on the line(s) below the
first brief summary. For anything more nuanced or complex, refer to the Notes
section. The Class Description should be easily digestible, so try not to bog
it down with highly technical components of the class.
You may split the additional summary into more than one paragraph.
...
"""
It’s important to be descriptive when writing this section. Look at some of the class descriptions in other classes throughout Scarabaeus and notice that they don’t assume the user has much prior knowledge about the class. It’s easy to write a quick two-sentence blurb about a class when you’ve been engrossed in its development for the past month, but make sure that you aren’t taking your intimate knowledge of it for granted when writing its description. Nothing should be ambiguous.
The Parameters Section#
The next section, the Parameters section, is also a mandatory inclusion in the Class Docstring. This is because it’s where
we provide information detailing the inputs, or parameters, of the class’ __init__ function. Where the Class Description told the
user what the class does, the Parameters Section tells the user how we expect them to set the class up to perform those actions.
Assume that we wish to document a class with an __init__ that looks like so:
from scarabaeus import ArrayWUnits
def __init__(self, arg_1 : ArrayWUnits, arg_two : float | list[float] = None,
arg_three : bool = False)
We can see that, per the style guide, all arguments have been typed correctly. We have three inputs, two of which are
optional. In order to document this properly, let’s first begin with arg_1, which we expect to be an ArrayWUnits object. Remember
from the Gneral Rules section that we should format this accordingly:
"""
...
Parameters
----------
arg_1 : ArrayWUnits
Short description of what we expect the argument to be. Since this is
an AWU input, we should also note what kind of units we expect or reccommend.
Recommend expressed in units of kilometers.
...
"""
Notice that we assigned the type of the argument by first writing out its name, followed by a space, colon, space, and finally its type. Next, on the line below indented once, we provide a description of the argument. It’s important that if our description spans more than one line that the indentation remains the same, otherwise Sphinx will read the next line as a separate bit of information. It’s also important to note that, by our documentation conventions, that description is completed with a period.
Now, let’s document arg_2, an optional input that can either be a single float or a list of floats. We’ll leave a blank line and on
the one below, start the same way as before. Note that, for clarity, instead of using the union operator, we choose to simply write out “or”.
Also, since it’s an optional argument, we need to note that as well, both in the typing as well at the end of the description. Notice that we
give the default value surrounded by a pair of back ticks. This tells Sphinx to render it as an in-line code block.
"""
...
Parameters
----------
arg_1 : ArrayWUnits
Short description of what we expect the argument to be. Since this is
an AWU input, we should also note what kind of units we expect or reccommend.
Recommend expressed in units of kilometers.
arg_2 : float or list[float], optional
Short description of what we expect the argument to be. Since this is an
optional argument, we note that after typing as well as at the end of
our description. Defaults to ``None``.
...
"""
Finally, we’ll document arg_3, another optional input, this time a boolean. For an input like a boolean where it can only be set to True
or False, we should explain what either option does. This is a good place to show the correct way to add some extra formatting in our docstrings:
unordered lists with the * delimiter. Since a boolean only has two states, we’ll only need two entries to the list. But, if required, we could
always add more entries for a more complicated setup.
Note
Ordered lists are also possible by using the #. delimiter instead of the * delimiter.
"""
...
Parameters
----------
arg_1 : ArrayWUnits
Short description of what we expect the argument to be. Since this is
an AWU input, we should also note what kind of units we expect or reccommend.
Recommend expressed in units of kilometers.
arg_2 : float or list[float], optional
Short description of what we expect the argument to be. Since this is an
optional argument, we note that after typing as well as at the end of
our description. Defaults to ``None``.
arg_3 : bool, optional
Short description of what we expect the argument to be. We'll use an
unordered list to give information on the potential states of the
boolean:
* ``True`` - whatever setting it to ``True`` does
* ``False`` - whatever setting it to ``False`` does
Notice that we've spaced the list by one line above and below. The list
will not render correctly otherwise. Defaults to ``False``.
...
"""
Filling out the Parameters section requires a balance between descriptiveness and conciseness. If you ever feel like you’re spending a lot of words to describe a parameter, you can always provide a more simplified explanation and refer to the Notes section. There you’ll have as much space as you want to provide detailed information about the parameter. We will cover the Notes section soon.
The Raises Section#
This Raises Section is the first discretionary inclusion in the Class Docstring. This means that if the information encapsulated in the subsection is not necessary, you do not need to include it. If your class doesn’t raise any complex errors, there’s no reason to include the Raises Section and you can remove it entirely from your Class Docstring.
However, if your class does have an error or errors that you feel it’s important to note, then you should document them here. Let’s assume our class raises the following errors:
if bad:
raise ValueError('Something very bad has happened.')
if more_bad:
raise TypeError('Another even worse thing has happened.')
The format for noting these errors is fairly similar to how we set up our parameters in the previous section. First we’ll paste the error call as well as the error itself under the Raises header. It’s important that we keep it all on one line, even if it it’s longer than the dosctring should be. Sphinx doesn’t like errors being broken up over multiple lines, so we’ll have to break the rules here.
"""
...
Raises
------
ValueError('Something very bad has happened.')
| Raised when you've done something very bad.
TypeError('Another even worse thing has happened.')
| Raised when you've done something even worse than the other error.
...
"""
Below the error, we indent once, place a | sign, a space, and then our explanation for why this error has been raised. Similarly to
the error line itself, we need to make sure that our description remains on a single line. The | is also necessary. This is somewhat
of a bandaid fix, but Sphinx will not render correctly otherwise. We must also make sure that, if we have more than one error, we leave a
blank line between the two definitions, since not doing so will also break Sphinx.
The See Also Section#
Our next discretionary inclusion in the Class Docstring is the See Also section. Note that at the beginning of this walkthrough we call
this subsection recommended. This is because, although not always necessary, it’s highly likely that at least one other class is relevant to the
current one. For example, Units and Dimensions are both relevant to ArrayWUnits and so are noted in its See Also section.
If there really is nothing that would be helpful to point to, then you can remove the See Also section from your docstring, but it’s strongly recommended that you give links to relevant classes. We can do this like so:
"""
...
See Also
--------
scarabaeus.Body : One-sentence description of why you might want to look here too.
scarabaeus.Units : Another short description of why you should look here as well.
...
"""
This is the simplest-to-format so far! All we need is to provide a reference to the relevant class for Sphinx to generate a link to. Once we’ve done that, we provide an optional blurb about why it’s relevant, and thats it!
The Notes Section#
The next section is the Notes Section, which is also discretionary but recommended because of its use in providing detailed information about a class. If a parameter or a property (see Property Docstrings below) requires an extra piece of information, or if a class requires some extra background info, the Notes Section is the place to put it.
Since you may want some extra formatting for your notes section, in additioned to the list functionality noted earlier, the below example also provides some other formatting techniques that you may wish to implement:
"""
...
Notes
-----
The notes section exists to provide additional or more in-depth information
pertaining to a class.
As noted above, this section contains examples for a few less common
formatting options. The first of which is creating tables like this one:
+---------+---------------+--------+-----------+
| Planets | Dwarf Planets | Moons | Asteroids |
+=========+===============+========+===========+
| Jupiter | Pluto | Tethys | Justitia |
+---------+---------------+--------+-----------+
| Saturn | Haumea | Phobos | Bennu |
+---------+---------------+--------+-----------+
See the table generator link given in the "Documenting Scripts for the Library
Reference" section of this document.
LaTeX syntax can be included like this :math:`r = \\frac{a(1-e^2)}{1+e \\cos\\theta)}`. Or entire
equations can also be created like so:
.. math::
\\phi = arctan(\\frac{esin\\nu}{1+ecos\\nu})
You can even include matrices:
.. math::
\\frac{\\partial\\mathbf{a}}{\\partial \\mathbf{r}} =
\\begin{bmatrix}
\\frac{\\partial a_x}{\\partial x} & \\frac{\\partial a_x}{\\partial y} & \\frac{\\partial a_x}{\\partial z} \\\\
\\frac{\\partial a_y}{\\partial x} & \\frac{\\partial a_y}{\\partial y} & \\frac{\\partial a_y}{\\partial z} \\\\
\\frac{\\partial a_z}{\\partial x} & \\frac{\\partial a_z}{\\partial y} & \\frac{\\partial a_z}{\\partial z}
\\end{bmatrix}
Note that double ``\\`` are required for Sphinx to recognize them.
Quotes can be created using a single indent surrounded by quotation marks:
"Quotes are very nice. - me"
...
"""
For examples of a good Notes Section, see the docs for EpochArray or Dimensions.
The References Section#
The next discretionary piece of the Class Docstring is the References Section. This is essentially a bibliography for your class and should be used as a way to easily reference anything that you’ve used in your code. This can include constants, equations, general concepts — anything that would be referenced in a paper.
You can also use these references as in-text citations throughout your Class Docstring. We’ll append another sentence to our Class Description section from before in the example below to highlight how to use this functionality:
"""
...
ORRCA Lab [1]_ is a great lab.
References
----------
.. [1] https://www.colorado.edu/faculty/mcmahon/orcca
.. [2] non-website sources should be cited in APA
...
"""
All citations that are not direct links to websites should be given in APA format unless otherwise necessary. For example, take reference 3
from an excerpt from Units.py’s Class Docstring:
"""
References
----------
.. [1] https://www.nist.gov/pml/owm/metric-si/si-units
.. [2] https://cneos.jpl.nasa.gov/glossary/LD.html
.. [3] XXVIII General Assembly of IAU, Beijing, 31 Aug 2012
References do not have to be included as in-text citations.
The Examples Section#
The Examples Section is the final component of the Class Docstring as well as one of the most important. However, there are many reasons why you may not include it, which is why it’s a discretionary, but highly recommended, inclusion. This section is a place to provide one or more examples showcasing the usage of your class. Don’t give extremely niche examples, but more is generally better in this case.
There are some situations where your class is dependent on one or more other classes to function. Other times, there is significant setup, or your class produces massive amounts of data that is difficult to parse or isn’t human-readable. In situations like these, don’t include an example. These sorts of “examples” are better suited for tutorial articles or demos.
The purpose of an example is to provide a quick and accessible chunk of code for a user to copy-paste and work with on their own. If the structure of your class is anthithetical to this goal, there is no need to include an example in your docstring.
"""
...
Examples
--------
Here we'll describe what we're providing an example for. In this case, we're using
our TemplateClass to perform some dummy operation. We'll use the code-block directive
to tell Sphinx to render our example as a copyable block of Python code below:
.. code-block:: python
# initial setup
import scarabaeus as scb
# call some dummy method
answer = scb.TemplateClass.general_template_method(1)
# make sure to provide the example's solution
>>> print(answer)
'Print out of the answer here'
We can place more examples if necssary, making sure to describe what we're doing in
words before providing the example code. Note that we don't need to import
Scarabaeus again in the code since it's already happened once above.
.. code-block:: python
# call some other dummy method
answer = scb.TemplateClass.alt_constr_template('fake_input.csv')
# make sure to provide the example's solution
>>> print(answer)
'Print out of the answer here'
"""
Note
You must provide a print out solution to any examples you provide. The code you place in the Examples section is purposefully not run by Sphinx during compilation firstly to reduce build time, but also, more importantly, to make sure developers check the code they’re providing works.
The code itself is placed in the code-block directive. By passing python to this directive, the code will be rendered as
a python script directly in the documentation. It also provides a button to copy-paste the entire block, allowing for easy testing for
users.
The Complete Class Docstring#
Now that we’ve completed all of the subsections of the Class Docstring, let’s look at the entire thing in one place:
"""
Here you should provide a sentence or two concisely explaining the class and its
functions.
If necessary, you can provide a longer explanation on the line(s) below the
first brief summary. For anything more nuanced or complex, refer to the Notes
section. The Class Description should be easily digestible, so try not to bog
it down with highly technical components of the class.
You may split the additional summary into more than one paragraph.
ORRCA Lab [1]_ is a great lab.
Parameters
----------
arg_1 : ArrayWUnits
Short description of what we expect the argument to be. Since this is
an AWU input, we should also note what kind of units we expect or reccommend.
Recommend expressed in units of kilometers.
arg_2 : float or list[float], optional
Short description of what we expect the argument to be. Since this is an
optional argument, we note that after typing as well as at the end of
our description. Defaults to ``None``.
arg_3 : bool, optional
Short description of what we expect the argument to be. We'll use an
unordered list to give information on the potential states of the
boolean:
* ``True`` - whatever setting it to ``True`` does
* ``False`` - whatever setting it to ``False`` does
Notice that we've spaced the list by one line above and below. The list
will not render correctly otherwise. Defaults to ``False``.
Raises
------
ValueError('Something very bad has happened.')
| Raised when you've done something very bad.
TypeError('Another even worse thing has happened.')
| Raised when you've done something even worse than the other error.
See Also
--------
scarabaeus.Body : One-sentence description of why you might want to look here too.
scarabaeus.Units : Another short description of why you should look here as well.
Notes
-----
The notes section exists to provide additional or more in-depth information
pertaining to a class.
As noted above, this section contains examples for a few less common
formatting options. The first of which is creating tables like this one:
+---------+---------------+--------+-----------+
| Planets | Dwarf Planets | Moons | Asteroids |
+=========+===============+========+===========+
| Jupiter | Pluto | Tethys | Justitia |
+---------+---------------+--------+-----------+
| Saturn | Haumea | Phobos | Bennu |
+---------+---------------+--------+-----------+
See the table generator link given in the "Documenting Scripts for the Library
Reference" section of this document.
LaTeX syntax can be included like this :math:`r = \\frac{a(1-e^2)}{1+e \\cos\\theta)}`. Or entire
equations can also be created like so:
.. math::
\\phi = arctan(\\frac{esin\\nu}{1+ecos\\nu})
You can even include matrices:
.. math::
\\frac{\\partial\\mathbf{a}}{\\partial \\mathbf{r}} =
\\begin{bmatrix}
\\frac{\\partial a_x}{\\partial x} & \\frac{\\partial a_x}{\\partial y} & \\frac{\\partial a_x}{\\partial z} \\\\
\\frac{\\partial a_y}{\\partial x} & \\frac{\\partial a_y}{\\partial y} & \\frac{\\partial a_y}{\\partial z} \\\\
\\frac{\\partial a_z}{\\partial x} & \\frac{\\partial a_z}{\\partial y} & \\frac{\\partial a_z}{\\partial z}
\\end{bmatrix}
Note that double ``\\`` are required for Sphinx to recognize them.
Quotes can be created using a single indent surrounded by quotation marks:
"Quotes are very nice. - me"
References
----------
.. [1] https://www.colorado.edu/faculty/mcmahon/orcca
.. [2] non-website sources should be cited in APA
Examples
--------
Here we'll describe what we're providing an example for. In this case, we're using
our TemplateClass to perform some dummy operation. We'll use the code-block directive
to tell Sphinx to render our example as a copyable block of Python code below:
.. code-block:: python
# initial setup
import scarabaeus as scb
# call some dummy method
answer = scb.TemplateClass.general_template_method(1)
# make sure to provide the example's solution
>>> print(answer)
'Print out of the answer here'
We can place more examples if necssary, making sure to describe what we're doing in
words before providing the example code. Note that we don't need to import
Scarabaeus again in the code since it's already happened once above.
.. code-block:: python
# call some other dummy method
answer = scb.TemplateClass.alt_constr_template('fake_input.csv')
# make sure to provide the example's solution
>>> print(answer)
'Print out of the answer here'
"""
This is a very informative Class Docstring! They can take up a lot of space in the code though, so if you’re working in an IDE like VSCode
(as you should be <scarabaeus-setup>_) don’t forget to collapse the docstring section so you can focus on your code by pressing the down
arrow that appears beside the line number of the top """ when you put your cursor over it.
Property Docstrings#
The next kind of docstring, the Property Docstring, is significantly simpler to implement. From the style guide, we have all of our properties defined in the properties section of the script. Each of these properties needs a docstring which describes what the property is. This description, just like the Class Docstring, is placed between two sets of three quotation marks, indented once, as in the (copy-pasteable) template below:
@property
def property_name(self) -> ArrayWUnits:
"""
PROPERTY DESCRIPTION
"""
Property descriptions should be fairly concise, especially if they’re containers for class inputs (no need to reiterate information you’ve already provided). If a particular property requires a significant amount of space, provide a simple explanation and refer to the Notes Section of the Class Docstring. There you can provide as much information as is necessary.
The only other important thing to note, which isn’t completely docstring related, is that we need to create a type hint for what kind of object the
property actually is using the -> symbol. This is important for Sphinx formatting.
"""
A description of the property. What does it represent in the class?
:base: TemplateClass
:type: Body
"""
Property Docstrings are the simplest of the three types of docstrings, but it’s vital that they’re included in all scripts because of the prominence and necessity of properties in documentation.
Method Docstrings#
The final kind of docstring, Method Docstrings, are very similar to the Class Docstring. It can consist of anywhere from three to eight subsections, noted below:
The Method Description - mandatory
The Parameters Section - mandatory
The Returns Section - mandatory
The Raises Section - at discretion
The See Also Section - at discretion
The Notes Section - at discretion
The References Section - at discretion
The Examples Section - at discretion
All of these sections are placed within the same docstring, book-ended by two sets of three quotation marks. All of the contents should be indented once inwards. It will take the below form (this is a helpful copy-paste template):
"""
METHOD DESC
Parameters
----------
arg : type
DESC
Returns
-------
describe : type
Explanation of return value named 'describe'.
Raises
------
REMOVE IF NO SPECIAL ERRORS
See Also
--------
REMOVE IF NO SEE ALSOS
Notes
-----
REMOVE IF NO NOTES
References
----------
REMOVE IF NO REFERENCES
Examples
--------
.. code-block:: python
# initial setup
import scarabaeus as scb
"""
This is the same structure as the Class Docstring with the addition of a Returns Section after the Parameters. However, note that the See Also, Notes, and Examples Sections are not recommended in this case. They are used significantly less often in Method Docstrings, and it is preferable to reduce their use so as not to overcrowd method documentation.
Since the only new addition to this docstring is the Returns Section, we only need to outline its use. See the section on Class Docstrings for a refresher on any of the other sections.
The Returns Section#
The Returns Section is structured identically to the Parameters Section, except it provides information on the value or values returned instead of the ones ingested. Assume that we have the following method:
def some_method(arg_1 : int) -> int:
"""
METHOD DOCSTRING GOES HERE
"""
# compute the answer
answer = arg_1 * 1
# return
return answer
In order to properly document the value returned by this method, we’ll write our Returns Section as follows:
"""
...
Returns
-------
answer : int
A description of the returned value. The name doesn't have to be the
same as the method's variable. It should describe what is actually
being returned.
...
"""
Thats it! Nothing too bad. Before we finish, let’s look at one other more complex situation:
def some_method(arg_1 : int) -> tuple[int, float]:
"""
METHOD DOCSTRING GOES HERE
"""
# compute the first part of the answer
first = arg_1 * 1
# and the second part
second = float(arg_1)
# return
return (first, second)
Here we have multiple return values, so we’ll want to also note where in the returned tuple it occurs.
"""
...
Returns
-------
first, second : tuple[int, float]
A tuple with the following values corresponding to
their respective indices:
* ``[0]`` = first : int
A description of the returned value.
* ``[1]`` = second : float
A description of the returned value.
...
"""
Method Docstrings should follow the same general rational <writing-rationale> as Class Docstrings - don’t be afraid to give too much information. An over-explanation will always be better than an under-explanation.
Further Reading#
Now that you know how to write for the external resource, continue reading on to the next section to learn how to direct Sphinx to include your additions, generate the updated version of the external resource, and update the online version.