From 24b31ad548a5a34ba57d6dbdd5a82a53a682a48d Mon Sep 17 00:00:00 2001 From: Svetlana Karslioglu Date: Tue, 27 May 2025 12:48:22 -0700 Subject: [PATCH] Updated Docstring Guidelines (markdown) --- Docstring-Guidelines.md | 69 +++++++++++++++++++++++++---------------- 1 file changed, 43 insertions(+), 26 deletions(-) diff --git a/Docstring-Guidelines.md b/Docstring-Guidelines.md index fe0da72..a41abd3 100644 --- a/Docstring-Guidelines.md +++ b/Docstring-Guidelines.md @@ -14,8 +14,10 @@ due to the nature of the PyTorch code. - [Documenting a class](#documenting-a-class) - [Documenting a function](#documenting-a-function) - [Documenting deprecated methods](#documenting-deprecated-methods) +- [reSTructuredText vs Markdown](#restructuredtext-vs-markdown) - [See Also](#see-also) + # Tooling 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 ``` - -# 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 @@ -273,14 +263,14 @@ Below is a quick reference of how to use MyST Markdown. | 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`` | +| `: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 @@ -308,15 +298,42 @@ This applies to all following directives: | 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`` | +| `: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`` | +| `:cpp:class:` | Reference a C++ class | {cpp:class}\`MyCppClass\` | +| `: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. \ No newline at end of file