cann-robotdocs(docs): Fix broken doc-site links and dead PTO-AS references

文件	最后提交记录	最后更新时间
src	docs(docs): Fix broken doc-site links and dead PTO-AS references	3 小时前
README.md	docs(docs): Remove PTO-AS docs from ISA manual	6 天前
README_zh.md	docs(docs): Remove PTO-AS docs from ISA manual	6 天前
check_mkdocs.py	submit all commits from 2025/12/31 to 2026/01/08	4 个月前
gen_pages.py	docs(docs): Fix broken doc-site links and dead PTO-AS references	3 小时前
mkdocs.yml	docs(docs): Remove PTO-AS docs from ISA manual	6 天前
requirements.txt	origin code	5 个月前

docs/mkdocs Documentation Build Guide

This directory is used to build the online documentation and local static documentation site for PTO Tile Lib, based on MkDocs (Material theme).

Documentation Content

The generated documentation covers:

PTO ISA instruction reference
Programming model and developer documentation
Getting started and usage guides
Kernel examples and directory guides

The documentation source files are mainly located under docs/mkdocs/src/.

Recommended Usage

Read documentation online: visit the Documentation Center
Preview locally or browse offline: build with MkDocs locally

Prerequisites

Python >= 3.9.x
pip

Note: Python has announced that 3.7.x/3.8.x are EOL. CANN will soon stop supporting these versions. Please upgrade to Python >= 3.9.x.

It is recommended to create a dedicated Python virtual environment first.

Option 1: Use MkDocs CLI

1. Install dependencies

python -m pip install -r docs/mkdocs/requirements.txt

2. Preview locally

python -m mkdocs serve -f docs/mkdocs/mkdocs.yml

After startup, the documentation is available at http://127.0.0.1:8000, and local changes are hot-reloaded automatically.

3. Build a static site

python -m mkdocs build -f docs/mkdocs/mkdocs.yml

The output is generated in docs/mkdocs/site/.

Option 2: Build via CMake

This is suitable for integrating documentation builds into development workflows or CI/CD.

1. Create a virtual environment and install dependencies

python3 -m venv .venv-mkdocs
source .venv-mkdocs/bin/activate  # Windows: .venv-mkdocs\Scripts\Activate.ps1
python -m pip install -r docs/mkdocs/requirements.txt

2. Configure and build

cmake -S docs -B build/docs -DPython3_EXECUTABLE=$PWD/.venv-mkdocs/bin/python
cmake --build build/docs --target pto_docs

Windows (PowerShell):

cmake -S docs -B build/docs -DPython3_EXECUTABLE="$PWD\.venv-mkdocs\Scripts\python.exe"
cmake --build build/docs --target pto_docs

The build output is located in build/docs/site/.

Directory Overview

mkdocs.yml: MkDocs configuration file
requirements.txt: documentation build dependencies
src/: documentation source directory
gen_pages.py: documentation page generation script
check_mkdocs.py: documentation build check script