[ONNX] Document ONNX diagnostics (pytorch#88371)

Reference pages:
- Landing page: https://docs-preview.pytorch.org/88371/onnx_diagnostics.html
- Individual rule: https://docs-preview.pytorch.org/88371/generated/onnx_diagnostics_rules/POE0004%3Aoperator-supported-in-newer-opset-version.html

An initial PR to setup the document generation for ONNX diagnostics.
* Add document page for ONNX diagnostics.
* Add document generation for diagnostics rules from `rules.yaml`.
* Add dependency on `myst-parser` for markdown to rst parsing.

More content to be added.

Pull Request resolved: pytorch#88371
Approved by: https://github.com/abock, https://github.com/justinchuby, https://github.com/malfet, https://github.com/kit1980

Author: BowenBao

docs/Makefile

@@ -17,8 +17,9 @@ figures:
 	@$(PYCMD) source/scripts/build_activation_images.py
 	@$(PYCMD) source/scripts/build_quantization_configs.py
 
-onnx_supported_aten_ops:
+onnx:
 	@$(PYCMD) source/scripts/onnx/build_onnx_supported_aten_op_csv_table.py
+	@$(PYCMD) source/scripts/onnx/build_onnx_diagnostics_rules_md.py $(SOURCEDIR)/generated/onnx_diagnostics_rules
 
 docset: html
 	doc2dash --name $(SPHINXPROJ) --icon $(SOURCEDIR)/_static/img/pytorch-logo-flame.png --enable-js --online-redirect-url https://pytorch.org/docs/ --force $(BUILDDIR)/html/
@@ -34,11 +35,11 @@ html-stable:
 	# See conf.py for more details.
 	RELEASE=1 make html
 
-.PHONY: help Makefile docset onnx_supported_aten_ops
+.PHONY: help Makefile docset onnx
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
-%: Makefile figures onnx_supported_aten_ops
+%: Makefile figures onnx
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 
 clean:

docs/requirements.txt

@@ -10,3 +10,4 @@ tensorboard==2.10.0
 python-etcd==0.4.5
 sphinx-copybutton==0.5.0
 sphinx-panels==0.4.1
+myst-parser==0.18.1

docs/source/conf.py

@@ -58,7 +58,8 @@
     'sphinxcontrib.katex',
     'sphinx.ext.autosectionlabel',
     'sphinx_copybutton',
-    'sphinx_panels'
+    'sphinx_panels',
+    'myst_parser',
 ]
 
 # build the templated autosummary files

docs/source/index.rst

@@ -85,6 +85,7 @@ Features described in this documentation are classified by release status:
    profiler
    nn.init
    onnx
+   onnx_diagnostics
    optim
    complex_numbers
    ddp_comm_hooks

docs/source/onnx_diagnostics.rst

@@ -0,0 +1,35 @@
+torch.onnx diagnostics
+======================
+
+.. contents:: :local:
+.. automodule:: torch.onnx._internal.diagnostics
+.. currentmodule:: torch.onnx._internal.diagnostics
+
+Overview
+--------
+
+NOTE: This feature is underdevelopment and is subject to change.
+
+The goal is to improve the diagnostics to help users debug and improve their model export to ONNX.
+
+- The diagnostics are emitted in machine parsable `Static Analysis Results Interchange Format (SARIF) <https://docs.oasis-open.org/sarif/sarif/v2.1.0/sarif-v2.1.0.html>`__.
+- A new clearer, structured way to add new and keep track of diagnostic rules.
+- Serve as foundation for more future improvements consuming the diagnostics.
+
+
+Diagnostic Rules
+----------------
+
+.. toctree::
+    :glob:
+
+    generated/onnx_diagnostics_rules/*
+
+API Reference
+-------------
+
+.. autoclass:: torch.onnx._internal.diagnostics.ExportDiagnostic
+    :members:
+
+.. autoclass:: torch.onnx._internal.diagnostics.infra.DiagnosticEngine
+    :members:

docs/source/scripts/onnx/build_onnx_diagnostics_rules_md.py

@@ -0,0 +1,37 @@
+import argparse
+import os
+from dataclasses import fields
+
+from torch.onnx._internal import diagnostics
+from torch.onnx._internal.diagnostics import infra
+
+
+def gen_docs(out_dir: str):
+    os.makedirs(out_dir, exist_ok=True)
+    for field in fields(diagnostics.rules):
+        rule = getattr(diagnostics.rules, field.name)
+        if not isinstance(rule, infra.Rule):
+            continue
+        title = f"{rule.id}:{rule.name}"
+        full_description_markdown = rule.full_description_markdown
+        assert (
+            full_description_markdown is not None
+        ), f"Expected {title} to have a full description in markdown"
+        with open(f"{out_dir}/{title}.md", "w") as f:
+            f.write(f"# {title}\n")
+            f.write(full_description_markdown)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Generate ONNX diagnostics rules doc in markdown."
+    )
+    parser.add_argument(
+        "out_dir", metavar="OUT_DIR", help="path to output directory for docs"
+    )
+    args = parser.parse_args()
+    gen_docs(args.out_dir)
+
+
+if __name__ == "__main__":
+    main()