docs: add documentation skeleton

CONTRIBUTING.md

@@ -70,20 +70,20 @@ Using Nvidia as an example:
 
 ```bash
 pip install .[dev] \
-  -C cmake.define.INFINI_RT_ROOT=/path/to/infinirt-prefix \
+  -C cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix \
   -C cmake.define.WITH_CPU=ON \
   -C cmake.define.WITH_NVIDIA=ON
 ```
 
-`/path/to/infinirt-prefix` is the InfiniRT install prefix, typically the value
+`/path/to/infini-rt-prefix` is the InfiniRT install prefix, typically the value
 used for InfiniRT's `CMAKE_INSTALL_PREFIX`. It should contain
 `include/infini/rt.h` and `lib/libinfinirt.so`.
 
 Auto-detection is supported for some platforms, so you can also let InfiniOps
 detect the device backends while still pointing it at the installed InfiniRT:
 
 ```bash
-pip install .[dev] -C cmake.define.INFINI_RT_ROOT=/path/to/infinirt-prefix
+pip install .[dev] -C cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix
 ```
 
 > `[dev]` installs optional development dependencies (e.g. `pytest`) that are not needed for production but required for development and testing. After the first install, subsequent installs only need `pip install .`.
@@ -102,7 +102,7 @@ For routine development and pull requests, start with a smoke build plus the smo
 
 ```bash
 python -m pip install .[dev] --no-build-isolation --no-deps \
-  --config-settings=cmake.define.INFINI_RT_ROOT=/path/to/infinirt-prefix \
+  --config-settings=cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix \
   --config-settings=cmake.define.INFINI_OPS_SMOKE_BUILD=ON
 python -m pytest tests -m smoke -q
 ```

README.md

@@ -15,10 +15,10 @@ InfiniOps is a high-performance, cross-platform operator library supporting mult
 Install InfiniRT first, then build InfiniOps with the InfiniRT install prefix:
 
 ```bash
-pip install . -C cmake.define.INFINI_RT_ROOT=/path/to/infinirt-prefix
+pip install . -C cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix
 ```
 
-`/path/to/infinirt-prefix` is the directory passed to InfiniRT as
+`/path/to/infini-rt-prefix` is the directory passed to InfiniRT as
 `CMAKE_INSTALL_PREFIX`; it should contain `include/infini/rt.h` and
 `lib/libinfinirt.so`.
 
@@ -27,7 +27,7 @@ platforms explicitly:
 
 ```bash
 pip install . \
-  -C cmake.define.INFINI_RT_ROOT=/path/to/infinirt-prefix \
+  -C cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix \
   -C cmake.define.WITH_CPU=ON \
   -C cmake.define.WITH_NVIDIA=ON
 ```
@@ -59,9 +59,18 @@ For Hygon builds, set `DTK_ROOT` to the DTK installation root if it is not insta
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for code style, commit conventions, PR workflow, development guide, and troubleshooting.
 
-## Development Docs
+## Documentation
 
+Full user and contributor documentation starts at [docs/README.md](docs/README.md).
+
+Useful entry points:
+
+- [Getting Started](docs/getting-started.md)
+- [Build and Test](docs/build.md)
+- [Backends](docs/backends.md)
+- [Operators](docs/api/operators.md)
 - [Adding ATen-backed operators](docs/aten-operators.md)
+- [Compatibility](docs/compatibility.md)
 
 ## License
 

docs/README.md

@@ -0,0 +1,37 @@
+# InfiniOps Documentation
+
+InfiniOps is a high-performance operator library for InfiniCore. It provides
+Python bindings and C++ operator implementations across CPU, NVIDIA, Iluvatar,
+Hygon, MetaX, Cambricon, Moore, Ascend, and other backends.
+
+The common public include entry is:
+
+```cpp
+#include <infini/ops.h>
+```
+
+The Python package entry is:
+
+```python
+import infini.ops
+```
+
+Start with these pages:
+
+- [Getting Started](getting-started.md): install InfiniRT, build InfiniOps, and
+  run a minimal operator call.
+- [Build and Test](build.md): build options, smoke builds, and test commands.
+- [Backends](backends.md): supported backend options and backend-specific
+  requirements.
+- [Core Types](api/core-types.md): tensors, devices, data types, handles, and
+  configuration objects.
+- [Operators](api/operators.md): the operator API model, dispatch, caching, and
+  implementation layout.
+- [Adding ATen-backed operators](aten-operators.md): generated and hand-written
+  PyTorch ATen backend guidance.
+- [Compatibility](compatibility.md): public API boundary, generated files, and
+  internal implementation headers.
+
+Generated API reference pages are intentionally left out of this first
+documentation pass. They should be added through a dedicated Doxygen build and
+publishing change.

docs/api/core-types.md

@@ -0,0 +1,78 @@
+# Core Types
+
+This page summarizes the core types used by InfiniOps operators. InfiniOps
+reuses the public InfiniRT runtime types where possible.
+
+## Tensor
+
+`infini::ops::Tensor` is an alias for `infini::rt::TensorView`.
+
+```cpp
+#include "tensor.h"
+
+std::vector<float> values(16);
+infini::ops::Tensor tensor{
+    values.data(),
+    std::vector<std::size_t>{4, 4},
+    infini::ops::Device{infini::ops::Device::Type::kCpu, 0}};
+```
+
+`Tensor` is a non-owning view. It stores the data pointer, shape, data type,
+device, and strides, but it does not own the memory it references.
+
+## Device
+
+`infini::ops::Device` is an alias for `infini::rt::Device`.
+
+Known device types include:
+
+- `Device::Type::kCpu`
+- `Device::Type::kNvidia`
+- `Device::Type::kIluvatar`
+- `Device::Type::kMetax`
+- `Device::Type::kMoore`
+- `Device::Type::kHygon`
+- `Device::Type::kCambricon`
+- `Device::Type::kAscend`
+
+Some source code also carries experimental or future device enum values. Treat
+documented build options in [Backends](../backends.md) as the supported user
+surface.
+
+## DataType
+
+`infini::ops::DataType` is imported from InfiniRT. Common values include:
+
+- `DataType::kInt8`, `DataType::kInt16`, `DataType::kInt32`, `DataType::kInt64`
+- `DataType::kUInt8`, `DataType::kUInt16`, `DataType::kUInt32`, `DataType::kUInt64`
+- `DataType::kFloat16`, `DataType::kBFloat16`, `DataType::kFloat32`, `DataType::kFloat64`
+
+InfiniOps also exposes type-list helpers such as `FloatTypes`,
+`ReducedFloatTypes`, `IntTypes`, `UIntTypes`, and `AllTypes` for template
+dispatch.
+
+## Handle
+
+`Handle` carries optional runtime resources for a call:
+
+- backend stream
+- workspace pointer
+- workspace size
+
+Operators that need temporary memory read the workspace from the handle.
+Callers that do not need custom stream or workspace handling can use the
+shorter `Op::Call(...)` form without an explicit handle.
+
+## Config
+
+`Config` carries operator configuration that is independent of tensor geometry.
+The most common field is `implementation_index`, which selects one of the
+active implementations for an operator and device.
+
+```cpp
+infini::ops::Config config;
+config.set_implementation_index(1);
+```
+
+Use the default config unless a specific backend implementation needs to be
+selected deliberately.

docs/api/operators.md

@@ -0,0 +1,99 @@
+# Operators
+
+InfiniOps operators are C++ classes with generated Python bindings. They share
+a common dispatch model across devices and backend implementations.
+
+## Public Call Shape
+
+Python users call generated functions from `infini.ops`:
+
+```python
+import infini.ops
+
+infini.ops.gemm(a, b, out)
+```
+
+C++ development code calls operator classes:
+
+```cpp
+infini::ops::Gemm::Call(a, b, out);
+```
+
+For calls that need a stream, workspace, or implementation selection, pass
+`Handle` and `Config` explicitly:
+
+```cpp
+infini::ops::Handle handle;
+infini::ops::Config config;
+
+config.set_implementation_index(1);
+infini::ops::Gemm::Call(handle, config, a, b, out);
+```
+
+## Dispatch Model
+
+Each operator has:
+
+- a base class under `src/base/<op>.h`
+- zero or more native implementations under `src/native/.../ops/<op>/`
+- optional PyTorch C++ implementations under `src/torch/ops/<op>/`
+- generated wrappers and Python bindings under `generated/`
+- tests under `tests/test_<op>.py`
+
+`Operator<Key, Device, Index>` specializations provide concrete
+implementations. `Device` selects the backend and `Index` selects the
+implementation slot for that operator on that backend.
+
+## Implementation Indexes
+
+Implementation indexes are local to an operator and device. Use an explicit
+index only when the backend exposes multiple implementations for the same
+operator.
+
+Generated ATen-backed wrappers reserve implementation index `8`. Hand-written
+backend implementations must avoid colliding with existing implementations for
+the same operator.
+
+## Operator Cache
+
+`Operator::Call(...)` caches constructed operator instances per thread. The
+cache key includes the config implementation index and tensor/scalar geometry.
+Tests can call `clear_cache()` on generated Python operator classes for module
+isolation.
+
+Code that changes tensor geometry, backend implementation selection, or
+workspace assumptions should account for this caching behavior.
+
+## Adding an Operator
+
+The standard path for a native operator is:
+
+1. Add the base class in `src/base/<op>.h`.
+2. Add one or more backend implementations under `src/native/.../ops/<op>/`.
+3. Add or update generated wrapper inputs if needed.
+4. Add focused tests under `tests/test_<op>.py`.
+5. Validate a smoke build plus the focused test on every affected backend.
+
+For PyTorch ATen-backed operators, see
+[Adding ATen-backed operators](../aten-operators.md). That page explains the
+generated backend path and the hand-written ATen backend path.
+
+## Smoke Coverage
+
+Smoke builds use an operator allowlist to keep routine validation short:
+
+```bash
+python -m pip install .[dev] --no-build-isolation --no-deps \
+  --config-settings=cmake.define.INFINI_RT_ROOT=/path/to/infini-rt-prefix \
+  --config-settings=cmake.define.WITH_CPU=ON \
+  --config-settings=cmake.define.INFINI_OPS_SMOKE_BUILD=ON
+```
+
+Then run:
+
+```bash
+python -m pytest tests -m smoke -q
+```
+
+Use full builds and broader tests for shared dispatch, wrapper generation,
+backend infrastructure, or high-risk operator changes.

docs/backends.md

@@ -0,0 +1,72 @@
+# Backends
+
+InfiniOps can be built for CPU and one accelerator backend at a time. The
+Python and operator APIs remain common, while device SDKs, compiler flags, and
+available implementations differ by backend.
+
+## Backend Options
+
+| Backend | CMake option | Notes |
+| --- | --- | --- |
+| CPU | `WITH_CPU` | Used as the smallest build and can be enabled with one accelerator backend. |
+| NVIDIA | `WITH_NVIDIA` | Requires CUDA Toolkit. |
+| Iluvatar | `WITH_ILUVATAR` | CUDA-compatible backend using the CoreX toolchain. |
+| Hygon | `WITH_HYGON` | Requires DTK. `DTK_ROOT` defaults to `/opt/dtk` when unset. |
+| MetaX | `WITH_METAX` | Requires the MetaX runtime and SDK paths. |
+| Cambricon | `WITH_CAMBRICON` | Requires Cambricon Neuware. |
+| Moore | `WITH_MOORE` | Requires MUSA Toolkit through `MUSA_ROOT`, `MUSA_HOME`, `MUSA_PATH`, or `/usr/local/musa`. |
+| Ascend | `WITH_ASCEND` | Requires Ascend CANN and, by default, the custom AscendC kernel toolchain. |
+| PyTorch C++ | `WITH_TORCH` | Adds ATen-backed implementations when PyTorch C++ headers and libraries are available. |
+
+## Device Auto-Detection
+
+`AUTO_DETECT_DEVICES=ON` probes device files such as `/dev/nvidia*` and turns on
+matching backend options. This is useful on configured developer machines but
+can be too implicit for reproducible CI or release builds.
+
+Prefer explicit backend options in scripts, CI, and release instructions.
+
+## Backend Selection in Tests
+
+The Python test harness accepts platform names through `--devices`, for example:
+
+```bash
+python -m pytest tests -m smoke -q --devices cpu nvidia
+```
+
+Supported selector names include:
+
+- `nvidia`
+- `metax`
+- `iluvatar`
+- `hygon`
+- `moore`
+- `cambricon`
+- `ascend`
+
+The harness maps those platform names to the PyTorch device type used by the
+installed backend, such as `cuda`, `musa`, `mlu`, or `npu`.
+
+## Implementation Layout
+
+Backend implementations live under:
+
+```text
+src/native/<category>/<platform>/ops/<op>/
+```
+
+Examples include:
+
+- `src/native/cpu/ops/gemm/`
+- `src/native/cuda/nvidia/ops/gemm/`
+- `src/native/ascend/ops/matmul/`
+- `src/native/cambricon/ops/rms_norm/`
+
+The PyTorch C++ backend uses:
+
+```text
+src/torch/ops/<op>/
+generated/torch/<op>/
+```
+
+Generated files are build artifacts and should not be edited by hand.