microsoft · justinchuby · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025 · Apr 25, 2025
diff --git a/.gitignore b/.gitignore
@@ -100,7 +100,7 @@ dmypy.json
 *.onnxlib
 **/onnx_backend_test_code/**
 docs/auto_examples/*
-docs/intermediate_representation/generated/*
+docs/**/generated/*
 tests/export/*
 tests/models/testoutputs/*
 tests/mylib.onnxlib

diff --git a/docs/_templates/classtemplate.rst b/docs/_templates/classtemplate.rst
@@ -7,8 +7,8 @@
 
 .. autoclass:: {{ name }}
     :members:
-
+    :undoc-members:
+    :member-order: bysource
 
 ..
   autogenerated from docs/_templates/classtemplate.rst
-  note it does not have :inherited-members:
diff --git a/docs/_templates/classtemplate_inherited.rst b/docs/_templates/classtemplate_inherited.rst
@@ -0,0 +1,16 @@
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline}}
+
+.. autoclass:: {{ name }}
+    :members:
+    :undoc-members:
+    :inherited-members:
+    :member-order: bysource
+
+
+..
+  autogenerated from docs/_templates/classtemplate.rst
diff --git a/docs/_templates/functiontemplate.rst b/docs/_templates/functiontemplate.rst
@@ -0,0 +1,12 @@
+.. role:: hidden
+    :class: hidden-section
+.. currentmodule:: {{ module }}
+
+
+{{ name | underline}}
+
+.. autofunction:: {{ name }}
+
+
+..
+  autogenerated from docs/_templates/functiontemplate.rst
diff --git a/docs/api/index.md b/docs/api/index.md
@@ -9,9 +9,16 @@ converter
 values
 ```
 
-## Tests and Tools
+## Model transformation
+
+```{toctree}
+optimizer
+rewriter
+version_converter
+```
+
+## Testing
 
 ```{toctree}
 testing
-tools
 ```
diff --git a/docs/api/optimizer.md b/docs/api/optimizer.md
@@ -0,0 +1,18 @@
+# onnxscript.optimizer
+
+```{eval-rst}
+.. automodule::onnxscript.optimizer
+.. currentmodule:: onnxscript
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: functiontemplate.rst
+
+    optimizer.optimize
+    optimizer.inline
+    optimizer.basic_constant_propagation
+    optimizer.fold_constants
+    optimizer.remove_unused_nodes
+```
diff --git a/docs/api/rewriter.md b/docs/api/rewriter.md
@@ -0,0 +1,23 @@
+# onnxscript.rewriter
+
+```{eval-rst}
+.. automodule::onnxscript.rewriter
+.. currentmodule:: onnxscript
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: functiontemplate.rst
+
+    rewriter.pattern
+    rewriter.rewrite
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: classtemplate.rst
+
+    rewriter.RewritePass
+```
diff --git a/docs/api/tools.md b/docs/api/tools.md
diff --git a/docs/api/version_converter.md b/docs/api/version_converter.md
@@ -0,0 +1,14 @@
+# onnxscript.version_converter
+
+```{eval-rst}
+.. automodule::onnxscript.version_converter
+.. currentmodule:: onnxscript
+```
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: functiontemplate.rst
+
+    version_converter.convert_version
+```
diff --git a/docs/index.md b/docs/index.md
@@ -103,7 +103,7 @@ result = MatmulAdd(x, wt, bias)
 Overview <self>
 tutorial/index
 api/index
-intermediate_representation/index
+ir/index
 auto_examples/index
 articles/index
 ```

diff --git a/...iate_representation/getting_started.ipynb → docs/ir/getting_started.ipynb b/...iate_representation/getting_started.ipynb → docs/ir/getting_started.ipynb
diff --git a/docs/intermediate_representation/index.md → docs/ir/index.md b/docs/intermediate_representation/index.md → docs/ir/index.md
@@ -19,6 +19,5 @@ An in-memory IR that supports the full ONNX spec, designed for graph constructio
 
 getting_started
 tensors
-ir_api
-generated
+ir_api/index
 ```
diff --git a/docs/intermediate_representation/ir_api.md → docs/ir/ir_api/core.md b/docs/intermediate_representation/ir_api.md → docs/ir/ir_api/core.md
@@ -2,23 +2,40 @@
 
 ```{eval-rst}
 .. automodule::onnxscript.ir
+.. currentmodule:: onnxscript
 ```
 
-## IR objects
+## Functions and constructors
 
 ```{eval-rst}
-.. currentmodule:: onnxscript
 .. autosummary::
     :toctree: generated
+    :template: functiontemplate.rst
     :nosignatures:
-    :template: classtemplate.rst
 
-    ir.Model
+    ir.load
+    ir.save
+    ir.from_proto
+    ir.to_proto
+    ir.tensor
+    ir.node
+```
+
+## Classes
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: classtemplate_inherited.rst
+    :nosignatures:
+
+    ir.TensorProtocol
+    ir.Value
+    ir.Node
     ir.Graph
+    ir.Model
     ir.GraphView
     ir.Function
-    ir.Node
-    ir.Value
     ir.Attr
     ir.RefAttr
     ir.Shape
@@ -38,8 +55,8 @@
 ```{eval-rst}
 .. autosummary::
     :toctree: generated
-    :nosignatures:
     :template: classtemplate.rst
+    :nosignatures:
 
     ir.DataType
     ir.AttributeType

diff --git a/docs/ir/ir_api/index.md b/docs/ir/ir_api/index.md
@@ -0,0 +1,13 @@
+# IR APIs
+
+```{toctree}
+:maxdepth: 1
+
+core
+ir_convenience
+ir_external_data
+ir_passes
+ir_passes_common
+ir_traversal
+ir_tape
+```
diff --git a/docs/ir/ir_api/ir_convenience.md b/docs/ir/ir_api/ir_convenience.md
@@ -0,0 +1,15 @@
+# ir.convenience
+
+```{eval-rst}
+.. automodule::onnxscript.ir.convenience
+.. currentmodule:: onnxscript.ir.convenience
+```
+
+
+```{eval-rst}
+.. autofunction:: convert_attribute
+.. autofunction:: convert_attributes
+.. autofunction:: replace_all_uses_with
+.. autofunction:: replace_nodes_and_values
+.. autofunction:: create_value_mapping
+```
diff --git a/docs/ir/ir_api/ir_external_data.md b/docs/ir/ir_api/ir_external_data.md
@@ -0,0 +1,20 @@
+# ir.external_data
+
+```{eval-rst}
+.. automodule::onnxscript.ir.external_data
+.. currentmodule:: onnxscript.ir.external_data
+```
+
+The `ir.external_data` module provides utilities for handling external data in ONNX models. It enables the conversion of tensors to and from external data files, allowing for efficient storage and manipulation of large tensor data. This is particularly useful for models with large initializers that exceed memory constraints.
+
+## Functions
+
+```{eval-rst}
+.. autofunction:: load_to_model
+.. autofunction:: unload_from_model
+.. autofunction:: convert_tensors_to_external
+.. autofunction:: convert_tensors_from_external
+.. autofunction:: set_base_dir
+```
+
+<!-- TODO: Create examples -->
diff --git a/docs/ir/ir_api/ir_passes.md b/docs/ir/ir_api/ir_passes.md
@@ -0,0 +1,39 @@
+# ir.passes
+
+```{eval-rst}
+.. automodule::onnxscript.ir.passes
+.. currentmodule:: onnxscript
+```
+
+## Use built-in passes
+
+Common, reusable passes are implemented in `ir.passes.common`. You can use {py:class}`ir.passes.Sequential <onnxscript.ir.passes.Sequential>` to chain passes or use {py:class}`ir.passes.PassManager <onnxscript.ir.passes.PassManager>` which supports early stopping if no changes are made.
+
+## Pass infrastructure
+
+Inherent {py:class}`ir.passes.InPlacePass <onnxscript.ir.passes.InPlacePass>` or {py:class}`ir.passes.FunctionalPass <onnxscript.ir.passes.FunctionalPass>` to define a pass. You will need to implement the `call` method which returns a {py:class}`ir.passes.PassResult <onnxscript.ir.passes.PassResult>`.
+
+Alternatively, inherent the base class `ir.passes.PassBase <onnxscript.ir.passes.PassBase>` and override the two properties `changes_input` and `in_place` to set properties of the pass.
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: classtemplate.rst
+    :nosignatures:
+
+    ir.passes.PassBase
+    ir.passes.InPlacePass
+    ir.passes.FunctionalPass
+    ir.passes.Sequential
+    ir.passes.PassResult
+    ir.passes.PassManager
+```
+
+## Errors
+
+```{eval-rst}
+.. autoexception:: onnxscript.ir.passes.InvariantError
+.. autoexception:: onnxscript.ir.passes.PreconditionError
+.. autoexception:: onnxscript.ir.passes.PostconditionError
+.. autoexception:: onnxscript.ir.passes.PassError
+```
diff --git a/docs/ir/ir_api/ir_passes_common.md b/docs/ir/ir_api/ir_passes_common.md
@@ -0,0 +1,25 @@
+# ir.passes.common
+
+```{eval-rst}
+.. currentmodule:: onnxscript
+```
+
+## Built-in passes
+
+
+```{eval-rst}
+.. autosummary::
+    :toctree: generated
+    :template: classtemplate.rst
+    :nosignatures:
+
+    ir.passes.common.unused_removal.RemoveUnusedNodesPass
+    ir.passes.common.unused_removal.RemoveUnusedFunctionsPass
+    ir.passes.common.unused_removal.RemoveUnusedOpsetsPass
+    ir.passes.common.inliner.InlinePass
+    ir.passes.common.topological_sort.TopologicalSortPass
+    ir.passes.common.constant_manipulation.LiftConstantsToInitializersPass
+    ir.passes.common.shape_inference.ShapeInferencePass
+    ir.passes.common.onnx_checker.CheckerPass
+    ir.passes.common.clear_metadata_and_docstring.ClearMetadataAndDocStringPass
+```
diff --git a/docs/ir/ir_api/ir_tape.md b/docs/ir/ir_api/ir_tape.md
@@ -0,0 +1,18 @@
+# ir.tape
+
+```{eval-rst}
+.. automodule:: onnxscript.ir.tape
+.. currentmodule:: onnxscript.ir.tape
+```
+
+The `ir.tape` module provides utilities for recording nodes and initializers to construct computational graphs or functions.
+
+## The `Tape` class
+
+The `Tape` class is a recorder that collects nodes and initializers created during the construction of a graph or function. It supports creating nodes with single or multiple outputs and registering initializers.
+
+```{eval-rst}
+.. autoclass:: Tape
+   :members:
+   :undoc-members:
+```
diff --git a/docs/ir/ir_api/ir_traversal.md b/docs/ir/ir_api/ir_traversal.md
@@ -0,0 +1,13 @@
+# ir.traversal
+
+```{eval-rst}
+.. automodule:: onnxscript.ir.traversal
+.. currentmodule:: onnxscript.ir.traversal
+```
+
+```{eval-rst}
+.. autoclass:: RecursiveGraphIterator
+   :members:
+   :undoc-members:
+   :special-members:
+```
diff --git a/docs/intermediate_representation/tensors.md → docs/ir/tensors.md b/docs/intermediate_representation/tensors.md → docs/ir/tensors.md
diff --git a/onnxscript/ir/_convenience/__init__.py b/onnxscript/ir/_convenience/__init__.py
@@ -107,7 +107,7 @@ def convert_attribute(
         A ``Attr`` object.
 
     Raises:
-        ValueError: If :param:`attr` is ``None`` and :param:`attr_type` is not provided.
+        ValueError: If ``attr`` is ``None`` and ``attr_type`` is not provided.
         TypeError: If the type of the attribute is not supported.
     """
     if attr is None:

diff --git a/onnxscript/ir/_core.py b/onnxscript/ir/_core.py
@@ -333,7 +333,7 @@ def __init__(
             value: The backing data of the tensor. It can be a numpy array compatible object or a DLPack compatible object.
                 When the dtype is not one of the numpy native dtypes, the value needs
                 to be ``uint8`` for 4-bit and 8-bit data types, and ``uint16`` for bfloat16
-                when the value is a numpy array; :param:`dtype` must be specified in this case.
+                when the value is a numpy array; ``dtype`` must be specified in this case.
             dtype: The data type of the tensor. It can be None only when value is a numpy array.
                 Users are responsible for making sure the dtype matches the value when value is not a numpy array.
             shape: The shape of the tensor. If None, the shape is obtained from the value.