Skip to content

Instantly share code, notes, and snippets.

@hectorcanto
Created September 1, 2024 14:00
Show Gist options
  • Save hectorcanto/60fc51f029fe450e99401e17e15fc125 to your computer and use it in GitHub Desktop.
Save hectorcanto/60fc51f029fe450e99401e17e15fc125 to your computer and use it in GitHub Desktop.
Google-style docstring exception with personal annotations
"""This is the docstring main line, I prefere them without a final dot
Descritption goes after a brealine, first line should not be multiline but second can be.
After it there can be many section like: Example, Usage, Returns, Attributes, Todo ... There
might special notation for documentation tooling like Sphinx or Handsdown. In general avoid
Avoid `Attributes` and `Returns` typing if specified in the hinting unless it is necessary for the tooling.
This is based in: [Sphinx Napoleon](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html)
Example:
Examples can be given using either the ``Example`` or ``Examples``
sections. Sections support any reStructuredText formatting, including
literal blocks::
$ python example_google.py
Section breaks are created by resuming unindented text. Section breaks
are also implicitly created anytime a new section starts.
Attributes:
module_level_variable1 (int): Module level variables may be documented in
either the ``Attributes`` section of the module docstring, or in an
inline docstring immediately following the variable.
Either form is acceptable, but the two should not be mixed. Choose
one convention to document module level variables and be consistent
with it.
Todo:
* For module TODOs
* You have to also use ``sphinx.ext.todo`` extension
.. _Google Python Style Guide:
http://google.github.io/styleguide/pyguide.html
"""
module_level_variable1 = 12345
module_level_variable2 = 98765
"""int: Module level variable documented inline.
The docstring may span multiple lines. The type may optionally be specified
on the first line, separated by a colon.
Some people are against multiline comment but there are plenty of cases to use them and the tools pick
them up perfectly.
"""
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment