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 10:22:21 -07:00
parent 722f46bf38
commit c269a591bd
1 changed files with 60 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
Docstring-Guidelines.md

@ -261,3 +261,62 @@ The following resources provide additional information and examples on how to wr
* [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
You can write your documentation files in .rst or MyST Markdown.
See [MyST Markdown documentation](https://myst-parser.readthedocs.io/en/v0.15.1/sphinx/use.html) for detailed instructions.
Below is a quick reference of how to use MyST Markdown.
### Python References
| reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------|
| `:py:class:` | Reference a class | `{py:class}`MyClass`` |
| `:py:func:` | Reference a function | `{py:func}`my_module.my_function`` |
| `:py:meth:` | Reference a method | `{py:meth}`MyClass.my_method`` |
| `:py:mod:` | Reference a module | `{py:mod}`my_module`` |
| `:py:attr:` | Reference an attribute | `{py:attr}`MyClass.my_attribute`` |
| `:py:data:` | Reference a data attribute or value | `{py:data}`MY_CONSTANT`` |
| `:py:exc:` | Reference an exception | `{py:exc}`MyException`` |
| `:py:obj:` | Reference any Python object | `{py:obj}`my_module.MyClass.my_function`` |
### Auto-Documentation Directives
Autodoc and autosummary directives should be wrapped in the `{eval-rst}` directive.
For example, this in .rst:
![rst-to-md_example1](https://github.com/user-attachments/assets/e9fb2193-eddd-4327-b4a9-5ca02166fe00)
would become this in MyST Markdown:
![rst-to-md_example2](https://github.com/user-attachments/assets/6281745f-2b63-471f-84c7-b6bf2edcf2ef)
This applies to all following directives:
* `.. autoclass::`
* `.. autofunction::`
* `.. automethod::`
* `.. autoattribute::`
* `.. autodata::`
* `.. autoexception::`
* `.. autoproperty::`
* `.. autosummary::`
### Document References
| reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------|
| `:doc:` | Reference another document | `{doc}`path/to/document`` |
| `:ref:` | Reference a labeled section or target | `{ref}`section-label`` |
| `:title:` | Reference a document's title | `{title}`Page Title`` |
| `:numref:` | Reference numbered items (e.g., figures) | `{numref}`figure-label`` |
### C++ References
| reSTructuredText| Purpose | MyST Markdown |
|-----------|---------|---------|
| `:cpp:class:` | Reference a C++ class | `{cpp:class}`MyCppClass`` |
| `:cpp:func:` | Reference a C++ function | `{cpp:func}`my_function`` |