Valid values for You can also make labels which can be anywhere (and not just before a section header), but when you reference them you also need to specify a label title:The one downside of this is that because a label in any document can be referenced from any other, You can also just reference a specific document. 3,470 3 3 gold badges 16 16 silver badges 38 38 bronze badges. :returns: The frobnicated baz Someone should look at it.To make your documentation look beautiful, you can take advantage of In order to tell Sphinx what and how to generate, we configure a helper file at This file allows us to release our code with all the metadata we want and note our extensions (the comments above explain how). Python code can include documentation right inside its source code. Docstrings are used to document the code and produce Sphinx pages. Surround text with one asterisk for italics, two asterisks for boldface, and Bulleted lists use asterisks, numbered lists use numbers, and nesting is done with indentation, like Markdown (though nested lists need to be surrounded by blank lines):Commented lines begin with two periods and a space (like a directive w/o the double colons):And multiline comments are also like directives w/o the colons:Sphinx supports including LaTeX-style equations in the documentation’s .rst files. Fortunately, Sphinx supports macros.Macros can come in handy for making your docstrings clean and easy to read, especially when using Intersphinx. This also comes in handy for linking to docs which aren’t written using Sphinx (and so intersphinx won’t work), for example:Although, presumably you’ll be wanting the same macros for most of your rst files. You can actually use any characters you want, but the convention is to use:You can add text in the normal way (by just adding text!). """"""Does some stuff """ The JSON format saves you from creating your own data formats, and is particularly easy to learn if you already know Python. (That the Fibonacci sequence is a geometric sequence rounded to the nearest whole number is one of my favorite little-known math facts. Pylint is your friend when you want to avoid arguing about code complexity. For example, to reference the NumPy Unfortunately, with intersphinx, you have to use the full class/function/method name (including the module name), and can’t use dot notation to have Sphinx search for the correct class/function/method to reference. We can access these docstrings using the __doc__ attribute. Here's how to use it with Python. bar (str): Bar to use on foo It also works pretty much the same way with First, you have to sign up for a ReadTheDocs account by going to To get ReadTheDocs to work with the Autodoc extension, there are a few other things you might have to worry about. float Parameters Returns: As mentioned above, Python docstrings are strings used right after the definition of a function, method, class, or module (like in Example 1). Using ReadTheDocs is easiest if you have a GitHub account and the code and docs for your package are hosted in a GitHub repository. In conf.py, setting the following only appends the __init__(self) docstring to the class docstring (the Sphinx autodoc documentation seems to agree that this is the expected behavior, but mentions nothing regarding the problem I'm trying to solve): :type bar: str To do that, create a Then, make ReadTheDocs aware of these dependencies by adding the following line to your You can also add a documentation status badge to your project’s """Does some stuff For example, instead of:Sphinx has more information about referencing Python objects For example, using raw reStructuredText, writing a function specification is horrific:However, especially when it comes to functions which have many parameters with multi-line descriptions (and long lists of types), I prefer The Napoleon extension allows you to write Numpy- or Google-style docstrings in your code, but causes Sphinx to render it correctly (as if you had written them with all the complicated reStructuredText roles).And to enable Napoleon, add the string to the list of extensions:Now in your documentation and docstrings, you can reference elements of that module.