- Notifications
You must be signed in to change notification settings - Fork547
Documentation Style Guide
Use the numpy docstring style. See examples here
Example NumPy Style Python Docstrings - napoleon 0.7 documentation
Any directive given in this document super-seeds those given in the style guide above. Our priority is to haveboth excellent generated documentation using Sphinxand readable tooltip docstrings.
"""One line descriptionLonger paragraph description. Each section of the docstring shouldbe seperated by a single line, except for rst directives (linesthat start with ".. " which should be seperated by 2 blank linesNote----An optional emphasised important single noteAttributes----------hermitian If True, `a` is a ...Raises------LinAlgError If the SVD computation does not converge.Returns-------b The pseudo-inverse of ...Synopsis--------Here is an extended description...Examples--------Example description.. runblock:: pycon>>> import roboticstoolbox as rtb>>> panda = rtb.models.Panda().ets()>>> solver = rtb.IK_QP()>>> Tep = panda.fkine([0, -0.3, 0, -2.2, 0, 2, 0.7854])>>> solver.solve(panda, Tep)Notes------ Lower priority notes- The pseudo-inverse of a matrix A, ...- Another noteReferences----------.. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.See Also--------scipy.linalg.pinv : Similar function in SciPy... versionchanged:: X.Y.Z Description of change"""
Class docstrings should be immediately below the class declaration and__init__ methods shouldnot have a docstring. See example:
classExampleClass():""" The summary line for a class docstring should fit on one line. Parameters ---------- param1 Description of `param1`. param2 Description of `param2`. Multiple lines are supported. param3 Description of `param3`. """def__init__(self,param1,param2,param3):""" Not here, there should be NO docstring here """pass
@propertydefname(self):""" Set/get image name An image has a string-valued name that can be read and written. The name is shown by the Image repr and when images are displayed graphically. Example ------- Example description .. runblock:: pycon >>> from machinevisiontoolbox import Image >>> img = Image.Read('flowers1.png') >>> img.name[-70:] >>> img.name = 'my image' >>> img.name Notes ----- Images loaded from a file have their name initially set to the full file pathname. See Also -------- :meth:`Read` """returnself._name@name.setterdefname(self,name):self._name=name
"""Use numbered references with the directive if you refer to the reference.Otherwise use a bullet point.References----------.. [1] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142... [2] G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.ORReferences----------- G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142.- G. Strang, *Linear Algebra and Its Applications*, 2nd Ed., Orlando, FL, Academic Press, Inc., 1980, pp. 139-142."""
Code examples should start with.. runblock:: pycon and the the example proceeding on the next line WITHOUT a blank line or an indent
"""Examples--------Example description.. runblock:: pycon>>> import roboticstoolbox as rtb>>> panda = rtb.models.Panda().ets()>>> solver = rtb.IK_QP()>>> Tep = panda.fkine([0, -0.3, 0, -2.2, 0, 2, 0.7854])>>> solver.solve(panda, Tep)"""
A typical class level rst file will look like
ClassName-ShortDescription (Optional)----------------------------------------..currentmodule::roboticstoolbox.robot.IK..autoclass::ClassName :show-inheritance:..rubric::Methods..autosummary:: :toctree:stubs~ClassName.meth1~ClassName.meth2~ClassName.meth3..rubric::PrivateMethods (Optional)..autosummary:: :toctree:stubs~ClassName._pmeth1~ClassName._pmeth2
Note how there is no entry for__init__ as that is documented with theautoclass directive.
Current Module
Use.. currentmodule:: roboticstoolbox.robot.IK to shorten future references within that module. With that directive I can now useIK_NR and/orIK_NR.step instead ofroboticstoolbox.robot.IK.IK_NR.step. This will also shorten what is rendered.
**The ~**
Use a~ to shorten a reference to the last section in what is rendered. For example~IK.IK_NR.step is rendered asstep in the resulting HTML files.