Skip to content

[Docathon] Convert cudnn_rnn_determinism.rst from rST to MyST Markdown#182701

Open
gaurav0107 wants to merge 2 commits intopytorch:mainfrom
gaurav0107:fix/182462-docathon-convert-cudnn-rnn-determinism-r
Open

[Docathon] Convert cudnn_rnn_determinism.rst from rST to MyST Markdown#182701
gaurav0107 wants to merge 2 commits intopytorch:mainfrom
gaurav0107:fix/182462-docathon-convert-cudnn-rnn-determinism-r

Conversation

@gaurav0107
Copy link
Copy Markdown

@gaurav0107 gaurav0107 commented May 6, 2026 •
edited
Loading

Summary

Converts docs/source/cudnn_rnn_determinism.rst to MyST Markdown as part of the Docathon h1-2025 track.

Fixes #182462

Conversions

  • .. warning:: -> :::{warning} colon-fence admonition (matches the established pytorch convention used by docs/source/storage.md, docs/source/masked.md, docs/source/fx.experimental.md)
  • Inline double-backtick literals (``CUDA_LAUNCH_BLOCKING=1``) -> single-backtick Markdown inline code (`CUDA_LAUNCH_BLOCKING=1`)
  • Trailing rST footnote-style hyperlink (`cuDNN 8 Release Notes`_ plus .. _cuDNN 8 Release Notes: <url>) -> inline Markdown link
  • No content changes; all environment variables, URLs, and guidance are byte-identical in meaning

History preservation

The conversion is in two commits: first a pure git mv (100% rename similarity), then the content conversion. git log --follow docs/source/cudnn_rnn_determinism.md traces back through the rename to the original 2020 addition (#40893). Verified locally.

Scope note: why torch/nn/modules/rnn.py is in this PR

The old docs/source/cudnn_rnn_determinism.rst was pulled into two class docstrings via .. include:: ../cudnn_rnn_determinism.rst:

  • torch/nn/modules/rnn.py:606 (nn.RNN)
  • torch/nn/modules/rnn.py:977 (nn.LSTM)

Sphinx parses .. include::'d files with the enclosing document's parser. Docstrings are rST (conf.py: source_suffix = ".rst"), so an MyST-syntax .md cannot substitute for the old .rst include target. After the rename, those two include directives would point at a non-existent path and fail the build-docs-python-false job, which runs with -W (warnings-as-errors, see docs/Makefile).

To keep the docstring output byte-identical and avoid breaking CI, the warning text is inlined directly into each of the two docstrings as a native .. warning:: block. The sibling .. include:: ../cudnn_persistent_rnn.rst is untouched because that .rst file still exists (separate Docathon issue).

Happy to split into two PRs (docs-only + rnn.py follow-up) if reviewers prefer a tighter scope.

Local verification

  • Verified git log --follow traces through the rename commit.
  • Verified no references to the old .rst path remain anywhere in the repo.
  • Verified no .. include:: ../cudnn_rnn_determinism.rst references remain.
  • lintrunner -a / spin lint were not run locally (no pytorch build env on this machine); relying on CI.

cc @svekars @sekyondaMeta @AlannaBurke

gaurav0107 added 2 commits May 7, 2026 01:38
@gaurav0107
Rename cudnn_rnn_determinism.rst to cudnn_rnn_determinism.md
22e1dbd 
Preparatory rename to preserve git history ahead of the rST -> MyST
content conversion in the follow-up commit. Part of the Docathon h1-2025
track (pytorch#182462).
@gaurav0107
Convert cudnn_rnn_determinism to MyST Markdown
ac3f397 
Converts the cuDNN RNN determinism note from rST to MyST syntax:
the ``.. warning::`` directive becomes a ``:::{warning}`` colon-fence
admonition, inline double-backtick literals collapse to single
backticks, and the trailing footnote-style hyperlink reference becomes
an inline Markdown link. No content changes.

The file was previously pulled into the ``nn.RNN`` and ``nn.LSTM`` class
docstrings in ``torch/nn/modules/rnn.py`` via ``.. include::``. Sphinx
parses the included file with the enclosing docstring's parser (rST),
so an MyST-syntax ``.md`` file can't be used the same way. Inline the
original rST warning into each docstring so doc rendering is unchanged
and the docs build doesn't break under ``-W``. The sibling
``.. include:: ../cudnn_persistent_rnn.rst`` is untouched.

Fixes pytorch#182462
@pytorch-bot
Copy link
Copy Markdown

pytorch-bot Bot commented May 6, 2026 •
edited
Loading

🔗 Helpful Links

🧪 See artifacts and rendered test results at hud.pytorch.org/pr/182701

Note: Links to docs will display an error until the docs builds have been completed.

❌ 3 New Failures

As of commit ac3f397 with merge base b007ef2 (image):

NEW FAILURES - The following jobs have failed:

This comment was automatically generated by Dr. CI and updates every 15 minutes.

@pytorch-bot
Copy link
Copy Markdown

pytorch-bot Bot commented May 6, 2026

This PR needs a release notes: label

If your changes are user facing and intended to be a part of release notes, please use a label starting with release notes:.

If not, please add the topic: not user facing label.

To add a label, you can comment to pytorchbot, for example
@pytorchbot label "topic: not user facing"

For more information, see
https://github.com/pytorch/pytorch/wiki/PyTorch-AutoLabel-Bot#why-categorize-for-release-notes-and-how-does-it-work.

@linux-foundation-easycla
Copy link
Copy Markdown

linux-foundation-easycla Bot commented May 6, 2026 •
edited
Loading

CLA Not Signed

@gaurav0107 gaurav0107 force-pushed the fix/182462-docathon-convert-cudnn-rnn-determinism-r branch from 9634e52 to ac3f397 Compare May 6, 2026 20:13
@gaurav0107
Copy link
Copy Markdown
Author

gaurav0107 commented May 6, 2026

@pytorchbot label "topic: not user facing" "module: docs" "topic: docs" "docathon-h1-2025"

@pytorch-bot pytorch-bot Bot added docathon-h1-2025 module: docs Related to our documentation, both in docs/ and docblocks topic: docs topic category topic: not user facing topic category labels May 6, 2026
@gaurav0107 gaurav0107 marked this pull request as ready for review May 6, 2026 20:22
@jbschlosser jbschlosser requested a review from svekars May 6, 2026 22:14
@jbschlosser jbschlosser added the triaged This issue has been looked at a team member, and triaged and prioritized into an appropriate module label May 6, 2026
@svekars svekars added docathon-2026 PyTorch Docathon H1 2026 easy label for easy docathon tasks and removed docathon-h1-2025 labels May 8, 2026
@svekars
Copy link
Copy Markdown
Contributor

svekars commented May 8, 2026

@claude

@claude
Copy link
Copy Markdown

claude Bot commented May 8, 2026 •
edited
Loading

Claude finished @svekars's task in 2m 51s —— View job

Review of PR #182701

  • Gather context and read changed files
  • Review the MyST Markdown conversion
  • Review the rnn.py changes
  • Post review feedback

Overall: The conversion is well-structured and the commit history approach (rename then convert) is good practice. The rnn.py inlining is correct and the rST syntax is valid. One issue worth addressing:

Issue: Orphaned .md file

After this PR, docs/source/cudnn_rnn_determinism.md is not referenced anywhere — it's not in a toctree, not included by any other file, and not linked from any document. Since myst_nb is loaded as a Sphinx extension (which registers .md as a valid source suffix), Sphinx will attempt to parse it as a standalone document. This could trigger a toctree contains reference to nonexisting document or document isn't included in any toctree warning, which would fail CI under -W (warnings-as-errors).

Recommendation: Either:

  1. Add the file to exclude_patterns in docs/source/conf.py (preferred — keeps the file for git history purposes without Sphinx trying to parse it), or
  2. Delete the .md file entirely (since its content is now inlined in rnn.py), or
  3. Add an orphan directive at the top of the .md file: 
    ---
orphan: true
---

Option 2 seems cleanest since the file now serves no purpose — the content is fully inlined into the two docstrings. The git history is already preserved through git log --follow regardless of whether the file still exists at HEAD.

Note: the sibling cudnn_persistent_rnn.rst avoids this issue because it's still actively included via .. include:: in rnn.py — Sphinx doesn't warn about files that are only used as include targets when they're .rst with no document title. But MyST .md files behave differently as they're registered as full source documents.

Minor observations (non-blocking)

  • The inlined rST in rnn.py is correct and matches the original .. include:: output byte-for-byte in rendered form.
  • The two-commit approach (rename + convert) properly preserves git log --follow history.
  • The MyST conversion uses :::{warning} with colon_fence — matches the project convention and myst_enable_extensions config.

svekars
svekars reviewed May 8, 2026
View reviewed changes
Comment thread torch/nn/modules/rnn.py
``batch_first`` argument is ignored for unbatched inputs.

.. include:: ../cudnn_rnn_determinism.rst
.. warning::
Copy link
Copy Markdown
Contributor

@svekars svekars May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the whole point of that file was to be able to reuse it. If .md doesn't load correctly, then we should leave .rst

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@svekars svekars svekars left review comments

@albanD albanD Awaiting requested review from albanD albanD is a code owner

@jbschlosser jbschlosser Awaiting requested review from jbschlosser jbschlosser is a code owner

@mikaylagawarecki mikaylagawarecki Awaiting requested review from mikaylagawarecki mikaylagawarecki is a code owner

Assignees

No one assigned

Labels

docathon-2026 PyTorch Docathon H1 2026 easy label for easy docathon tasks module: docs Related to our documentation, both in docs/ and docblocks open source topic: docs topic category topic: not user facing topic category triaged This issue has been looked at a team member, and triaged and prioritized into an appropriate module

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Docathon] Convert cudnn_rnn_determinism.rst from rST to MyST Markdown

4 participants

@gaurav0107 @svekars @pytorchbot @jbschlosser