frozenleaves/pytorch
1
0
Fork 0
mirror of https://github.com/pytorch/pytorch.git synced 2025-10-20 21:14:14 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated Docstring Guidelines (markdown)

Svetlana Karslioglu
2025-05-27 12:48:22 -07:00
parent c269a591bd
commit 24b31ad548
1 changed files with 43 additions and 26 deletions
Download Patch File Download Diff File Expand all files Collapse all files

69
Docstring-Guidelines.md

@ -14,8 +14,10 @@ due to the nature of the PyTorch code.
- [Documenting a class](#documenting-a-class) - [Documenting a class](#documenting-a-class)
- [Documenting a function](#documenting-a-function) - [Documenting a function](#documenting-a-function)
- [Documenting deprecated methods](#documenting-deprecated-methods) - [Documenting deprecated methods](#documenting-deprecated-methods)
- [reSTructuredText vs Markdown](#restructuredtext-vs-markdown)
- [See Also](#see-also) - [See Also](#see-also)
# Tooling # Tooling
The PyTorch project uses a combination of tools to build and generate documentation from docstrings. The PyTorch project uses a combination of tools to build and generate documentation from docstrings.
@ -249,18 +251,6 @@ def old_function(x, y):
""" """
return x + y return x + y
``` ```
# See also
The following resources provide additional information and examples on how to write and generate documentation for Python projects.
* [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/): The official Python Enhancement Proposal which provides conventions for Python docstrings.
* [Sphinx](https://www.sphinx-doc.org/en/master/): A tool that makes it easy to create intelligent and beautiful documentation.
* [Sphinx Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html): Instructions for Sphinx on how to handle specific elements of the documentation, such as code blocks, images, or sections.
* [Autosummary](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html): A Sphinx extension that generates function/method/attribute summary lists.
* [Autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html): A Sphinx extension that automatically extracts documentation from your Python modules.
* [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html): Examples and guidelines for writing Python docstrings in Google style.
* [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html): A guide to the markup syntax used by Sphinx and autosummary.
## reSTructuredText vs Markdown ## reSTructuredText vs Markdown
@ -273,14 +263,14 @@ Below is a quick reference of how to use MyST Markdown.
| reSTructuredText| Purpose | MyST Markdown | | reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------| |-----------|---------|---------|
| `:py:class:` | Reference a class | `{py:class}`MyClass`` | | `:py:class:` | Reference a class | {py:class}\`MyClass\` |
| `:py:func:` | Reference a function | `{py:func}`my_module.my_function`` | | `:py:func:` | Reference a function | {py:func}\`my_module.my_function\` |
| `:py:meth:` | Reference a method | `{py:meth}`MyClass.my_method`` | | `:py:meth:` | Reference a method | {py:meth}\`MyClass.my_method\` |
| `:py:mod:` | Reference a module | `{py:mod}`my_module`` | | `:py:mod:` | Reference a module | {py:mod}\`my_module\` |
| `:py:attr:` | Reference an attribute | `{py:attr}`MyClass.my_attribute`` | | `:py:attr:` | Reference an attribute | {py:attr}\`MyClass.my_attribute\` |
| `:py:data:` | Reference a data attribute or value | `{py:data}`MY_CONSTANT`` | | `:py:data:` | Reference a data attribute or value | {py:data}\`MY_CONSTANT\` |
| `:py:exc:` | Reference an exception | `{py:exc}`MyException`` | | `:py:exc:` | Reference an exception | {py:exc}\`MyException\` |
| `:py:obj:` | Reference any Python object | `{py:obj}`my_module.MyClass.my_function`` | | `:py:obj:` | Reference any Python object | {py:obj}\`my_module.MyClass.my_function\` |
### Auto-Documentation Directives ### Auto-Documentation Directives
@ -308,15 +298,42 @@ This applies to all following directives:
| reSTructuredText| Purpose | MyST Markdown | | reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------| |-----------|---------|---------|
| `:doc:` | Reference another document | `{doc}`path/to/document`` | | `:doc:` | Reference another document | {doc}\`path/to/document\` |
| `:ref:` | Reference a labeled section or target | `{ref}`section-label`` | | `:ref:` | Reference a labeled section or target | {ref}\`section-label\` |
| `:title:` | Reference a document's title | `{title}`Page Title`` | | `:title:` | Reference a document's title | {title}\`Page Title\` |
| `:numref:` | Reference numbered items (e.g., figures) | `{numref}`figure-label`` | | `:numref:` | Reference numbered items (e.g., figures) | {numref}\`figure-label\` |
### C++ References ### C++ References
| reSTructuredText| Purpose | MyST Markdown | | reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------| |-----------|---------|---------|
| `:cpp:class:` | Reference a C++ class | `{cpp:class}`MyCppClass`` | | `:cpp:class:` | Reference a C++ class | {cpp:class}\`MyCppClass\` |
| `:cpp:func:` | Reference a C++ function | `{cpp:func}`my_function`` | | `:cpp:func:` | Reference a C++ function | {cpp:func}\`my_function\` |
### Anchors
Often in pytorch docs, you can see anchors like this:
```
.. _myanchor:
Heading
-------
```
You can convert like this:
```
(myanchor)=
## Heading
```
# See also
The following resources provide additional information and examples on how to write and generate documentation for Python projects.
* [PEP 257 - Docstring Conventions](https://peps.python.org/pep-0257/): The official Python Enhancement Proposal which provides conventions for Python docstrings.
* [Sphinx](https://www.sphinx-doc.org/en/master/): A tool that makes it easy to create intelligent and beautiful documentation.
* [Sphinx Directives](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html): Instructions for Sphinx on how to handle specific elements of the documentation, such as code blocks, images, or sections.
* [Autosummary](https://www.sphinx-doc.org/en/master/usage/extensions/autosummary.html): A Sphinx extension that generates function/method/attribute summary lists.
* [Autodoc](https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html): A Sphinx extension that automatically extracts documentation from your Python modules.
* [Google Style Python Docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html): Examples and guidelines for writing Python docstrings in Google style.
* [reStructuredText Primer](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html): A guide to the markup syntax used by Sphinx and autosummary.