Fixed formatting

Svetlana Karslioglu
2024-05-22 11:04:10 -07:00
parent 81e84c45d8
commit 45f8f903a9

@ -87,6 +87,7 @@ Raw strings are often used for docstrings that include LaTeX math expressions, r
# Including content into the generated documentation set
In the PyTorch codebase, you'll find both autodoc and autosummary conventions being used to publish the documentation. While both autosummary and autodoc are powerful tools for generating documentation, there are several reasons why autosummary might be preferred over autodoc in certain situations.
Autosummary generates concise summary tables for modules, classes, and functions and places them in the generated directory in the documentation build. This makes it easier for users to get an overview of the API and navigate to the specific sections they are interested in. Autodoc, on the other hand, generates a one pager documentation for all functions in a class which is often overwhelming and hard for the users to read.
In most cases, you'll find that autosummary is a better way of organizing API documentation for PyTorch.
@ -184,7 +185,7 @@ When documenting a function, the docstring should include the following sections
* **Args:** A description of the function's arguments, including the type of each argument in parenthesis. For example: x (Tensor).
* **Returns:** A description of the return value and its type. Add a column after the value and before the type. For example, Tensor: The sum of x and y.
* **Raises:** Any exceptions that the function may raise. For example, TypeError: x and y are not the same type.
* **Examples:** Examples of how to use the function. Each function should have at least one example but less than 5. The examples should be written in doctest format, which means they should start with >>>. For example:
* **Examples:** Examples of how to use the function. Each function should have at least one example but less than 5. The examples should be written in doctest format, which means they should start with `>>>`. For example:
```
>>> x = torch.tensor([1, 2])