Understanding the Use of "Two Dots" in Python Docstrings

Question

I'm currently in the process of learning about Python docstrings, particularly in the context of Google-style, NumPy-style, and Sphinx-style formatting. I've noticed that sometimes there are two dots at the beginning of a line in these docstrings, and I'm curious to understand their significance and usage. What do these mean and how are they used?

Additionally, I've come across situations where some lines have two colons (e.g., .. math::), while others have just one (e.g., .. _label-text:). I would appreciate it if someone could explain the differences and provide guidance on when to use one or the other.

For reference, here are some examples from different sources that showcase these patterns:

• numpydoc - 13. Notes

  .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
  
  .. image:: filename
  

• numpydoc - 14. References

  .. [1] O. McNoleg, "The integration of GIS, remote sensing,
     expert systems and adaptive co-kriging for environmental habitat
     modelling of the Highland Haggis using object-oriented, fuzzy-logic
     and neural-network techniques," Computers & Geosciences, vol. 22,
     pp. 585-588, 1996.
  
  

• python-tooling-example

  .. _label-text:
  
  Example title
  -------------
  

  .. directive-name:: arg1 arg2 arg3
      :named-parameter1: value1
      :named-parameter2: value2
  
      Text that the directive should be applied to. it
      must be indented. also note the blank link before
      the text starts.
  
      The text block can span multiple paragraphs, and
      ends when indentation returns to its previous level.
  
      .. note::
  
          Directives can be nested like this. Notice the
          simpler syntax for directives that do not
          require any arguments.
  

• Example Google Style Python Docstrings

  .. _Google Python Style Guide:
     http://google.github.io/styleguide/pyguide.html
  

I have search lot of website on goolge, but didn't get a good answer. I expect some one can help me to understand what is these and how to use?

Answer 1

Straight from Sphinx documentation (https://python-tooling-example.readthedocs.io/en/latest/docs.html)

Two dots, a space, and an underscore mark the start of a label. A colon marks its end.:

.. _label-text:

Example title

---

The syntax for using a directive is similar to a label. Two dots and space mark the start of a directive (note no underscore!) and two colons demarcate the end of the directive’s name:

.. directive-name:: arg1 arg2 arg3
    :named-parameter1: value1
    :named-parameter2: value2

    Text that the directive should be applied to. it
    must be indented. also note the blank link before
    the text starts.

    The text block can span multiple paragraphs, and
    ends when indentation returns to its previous level.

    .. note::

        Directives can be nested like this. Notice the
        simpler syntax for directives that do not
        require any arguments.

So, in laymen terms, seems a way to create structure in docstring layout. It feels somehow latex-ish.

Answer 2

These docstrings use the markup language reStructuredText. See the formal specification and the cheat sheet