simpler/mkdocs.yml at main · hw-native-sys/simpler · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
INHERIT: .site-theme/docs-theme/base.yml

site_name: simpler
site_description: "Simple Runtime — make writing runtime simpler"
site_url: https://www.pypto.ai/simpler/
repo_url: https://github.com/hw-native-sys/simpler
repo_name: hw-native-sys/simpler
edit_uri: edit/main/docs/

docs_dir: docs
# Build inputs that live under docs/ but are not content.
exclude_docs: |
  _hooks/
  requirements.txt
  theme-revision.txt

theme:
  custom_dir: .site-theme/docs-theme/overrides
  language: en
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.indexes
    - navigation.top
    - navigation.footer
    - content.action.edit
    - content.code.copy
    - search.suggest
    - search.highlight
    - toc.follow

extra:
  pypto_project: simpler

# A page absent from nav builds fine by default and only shows up as an INFO
# line, so it silently disappears from the site's navigation. Promote it to a
# warning, which --strict then treats as a failure.
validation:
  nav:
    omitted_files: warn
    not_found: warn
  links:
    # A directory link needs a README.md or index.md landing page. Otherwise
    # MkDocs leaves the URL unchanged and the published site serves a 404.
    unrecognized_links: warn
    # Defaults to `info`, which --strict ignores, so a link to a heading that
    # was renamed or never existed builds clean and 404s in the reader's
    # browser. Note the two slug dialects differ: GitHub keeps the doubled
    # hyphen a heading like "FAQ / Debug Guide" produces, MkDocs collapses it.
    # Headings here avoid the punctuation that splits them.
    anchors: warn

# Deliberate omissions: these are accumulating logs and design sets, reached
# through their own index pages rather than the sidebar. Listing every entry in
# nav would bury the rest of the tree. Declaring them here keeps
# omitted_files strict for everything else.
not_in_nav: |
  investigations/*
  remote-l3-worker-design/*
  troubleshooting/device-error-codes/*

hooks:
  - docs/_hooks/repo_links.py

plugins:
  - search
  - mkdocstrings:
      handlers:
        python:
          paths: [python]
          options:
            docstring_style: google
            show_source: false
            show_root_heading: true
            members_order: source
            filters: ["!^_"]
            separate_signature: true
            show_signature_annotations: true

markdown_extensions:
  - admonition
  - attr_list
  - tables
  - toc: { permalink: true }
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.highlight: { anchor_linenums: true }

nav:
  - Home: README.md
  - Using simpler:
      - Overview: user/README.md
      - Getting Started: getting-started.md
      - Installation: install.md
      - Capability Survey: capability-survey.md
      - How-to:
          - Write and run a kernel: user/how-to/write-and-run-a-kernel.md
          - Run on multiple chips: user/how-to/run-on-multiple-chips.md
          - Profile a kernel: user/how-to/profile-a-kernel.md
          - Debug a failed run: user/how-to/debug-a-failed-run.md
      - Reference:
          - Python API: user/reference/python-api.md
          - Command line and tools: user/reference/cli.md
          - Generated API:
              - simpler.worker: user/reference/api/worker.md
              - simpler.task_interface: user/reference/api/task_interface.md
              - simpler.orchestrator: user/reference/api/orchestrator.md
  - Architecture:
      - Chip-Level Architecture: chip-level-arch.md
      - Hierarchical Level Runtime: hierarchical-level-runtime.md
      - Task Flow: task-flow.md
      - Buffer Memory Model: buffer-abi.md
      - Orchestrator: orchestrator.md
      - Scheduler: scheduler.md
      - TMR A2/A3 vs A5: tensormap-and-ringbuffer-a2a3-vs-a5.md
      - A5 AICPU core selection: design/a5-fg-pg-core-selection.en.md
      - Run completion fences: design/run-completion-fence.md
      - Worker Manager: worker-manager.md
      - Hardware:
          - Overview: hardware/README.md
          - Chip architecture: hardware/chip-architecture.md
          - Cache coherency: hardware/cache-coherency.md
          - MMIO performance: hardware/mmio-performance.md
          - CANN source references: hardware/cann-source-references.md
  - Kernels:
      - AICore Kernel Programming: aicore-kernel-programming.md
      - a5 SIMT Launch: simt-launch.md
      - Manual Scope: manual-scope.md
      - WAR Anti-Dependencies: war-anti-dependency.md
      - TPUSH/TPOP: tpush-tpop.md
  - Launch and linking:
      - AICPU Kernel Launch: aicpu-kernel-launch-mechanisms.md
      - Dynamic Linking: dynamic-linking.md
      - Callable Identity: callable-identity-registration.md
      - Callable IPC Registration: callable-ipc-dynamic-register.md
      - Python Callable Serialization: python-callable-serialization.md
  - Multi-chip and comm:
      - Communication Domains: comm-domain.md
      - L3-L2 Orchestrator Comm: l3-l2-orch-comm.md
      - L3-L2 Message Queue: l3-l2-message-queue.md
      - Directed NEXT_LEVEL Scheduling: directed-next-level-scheduling.md
      - Remote L3 Worker Design:
          - Overview: remote-l3-worker-design.md
          - Design document index: remote-l3-worker-design/README.md
      - MPI L3 group mailbox: mpi-l3-mailbox.md
  - Profiling and DFX:
      - Overview: dfx/README.md
      - Profiling Framework: dfx/profiling-framework.md
      - Config naming rules: dfx/profiling-config-naming.md
      - Name map: dfx/profiling-name-map.md
      - Log System: logging.md
      - L2 Timing: dfx/l2-timing.md
      - Host trace: dfx/host-trace.md
      - hbg bind phases: dfx/hbg-bind-phases.md
      - Device phases: dfx/device-phases.md
      - Scheduler-overhead model: dfx/sched-overhead-model.md
      - Chip Swimlane: dfx/chip-swimlane-profiling.md
      - Core Swimlane: dfx/core-swimlane-profiling.md
      - PMU: dfx/pmu-profiling.md
      - Args dump: dfx/args-dump.md
      - dep_gen: dfx/dep-gen.md
      - Scope stats: dfx/scope-stats.md
      - Backpressure: dfx/backpressure-design.md
      - Buffer capacity audit: dfx/dfx-buffer-capacity-audit.md
  - Build and test:
      - Developer Guide: developer-guide.md
      - Testing: testing.md
      - CI Pipeline: ci.md
      - Python Packaging: python-packaging.md
      - Sanitizers: sanitizers.md
      - Sim Multi-Device Isolation: sim-multi-device-isolation.md
  - Troubleshooting:
      - Overview: troubleshooting/README.md
      - Device error codes:
          - Overview and code reference: troubleshooting/device-error-codes.md
          - Diagnostic guide index: troubleshooting/device-error-codes/README.md
      - Local timeout defaults: troubleshooting/local-timeout-defaults.md
      - A2/A3 scheduling tails: troubleshooting/a2a3-scheduling-tails.md
      - a2a3 507899 AICPU shared-SO fault: troubleshooting/a2a3-507899-aicpu-shared-so-fault.md
      - Sim oversubscription hang: troubleshooting/sim-oversubscription-hang.md
      - macOS build: troubleshooting/macos-build.md
      - macOS libomp collision: troubleshooting/macos-libomp-collision.md
      - cpput gtest ABI: troubleshooting/ut-cpp-gtest-abi.md
      - a2a3 worker retirement: troubleshooting/a2a3-worker-retirement.md
  - Investigations: investigations/README.md