wehub-resource-sync
173 lines
7.9 KiB
Markdown
173 lines
7.9 KiB
Markdown
# Documentation system
|
|
|
|
Source for https://www.rerun.io/docs and related API reference sites.
|
|
|
|
## Sites overview
|
|
|
|
| Site | URL | Content source (this repo) | Build tool |
|
|
|------------|------------------------------|--------------------------------|-------------------------------------------------|
|
|
| Main docs | `rerun.io/docs` | `docs/content/` | [landing](https://github.com/rerun-io/landing) (Vercel) |
|
|
| Python API | `ref.rerun.io/docs/python/` | Docstrings in `rerun_py/` | MkDocs + mkdocstrings |
|
|
| C++ API | `ref.rerun.io/docs/cpp/` | `///` comments in `rerun_cpp/` | Doxygen |
|
|
| JS API | `ref.rerun.io/docs/js/` | Source in `rerun_js/` | TypeDoc |
|
|
| Rust API | `docs.rs/rerun` | `///` comments in `crates/` | docs.rs (automatic on publish) |
|
|
|
|
The main docs site is rendered by a **separate repository** ([rerun-io/landing](https://github.com/rerun-io/landing)) deployed on Vercel. It reads `docs/content/` from this repo at the commit specified by the `RELEASE_COMMIT` env var (normally pointing at the `docs-latest` branch). To preview the main docs site locally you need to clone the `landing` repo and follow its setup instructions. PRs in this repo that touch `docs/content/` automatically get a Vercel preview deployment link posted as a PR comment.
|
|
|
|
## Key commands
|
|
|
|
```
|
|
pixi run py-docs-serve # Serve Python API docs locally (hot-reload)
|
|
pixi run py-docs-build # Build Python API docs
|
|
pixi run -e cpp cpp-docs # Build C++ API docs (output: rerun_cpp/docs/html/)
|
|
pixi run js-docs # Build JS API docs
|
|
pixi run js-docs-serve # Serve JS docs locally
|
|
pixi run codegen # Regenerate type reference docs (+ all SDK code) from .fbs
|
|
pixi run man # Regenerate CLI reference at docs/content/reference/cli.md
|
|
pixi run search-index # Build Meilisearch search index
|
|
pixi run mdlint # Lint markdown files
|
|
pixi run link-check # Check for broken links
|
|
```
|
|
|
|
## Main docs site (`docs/content/`)
|
|
|
|
Markdown files with YAML frontmatter, organized hierarchically:
|
|
|
|
```
|
|
docs/content/
|
|
index.md # Entry point
|
|
overview/ # Installation, what is Rerun
|
|
getting-started/ # Quick start, data-in/out, configure viewer
|
|
concepts/ # Logging, visualization, querying
|
|
howto/ # Integration guides, tutorials
|
|
reference/
|
|
cli.md # Auto-generated (pixi run man)
|
|
sdk/ # SDK operating modes, micro-batching
|
|
types/ # Auto-generated type docs (pixi run codegen)
|
|
archetypes/ # e.g. points3d.md
|
|
components/ # e.g. position3d.md
|
|
datatypes/ # e.g. vec3d.md
|
|
views/ # e.g. spatial3d_view.md
|
|
viewer/ # Viewer reference
|
|
development/ # Contributor docs
|
|
_redirects.yaml # URL redirect mappings (old path → new path)
|
|
```
|
|
|
|
### Frontmatter
|
|
|
|
Every page needs YAML frontmatter:
|
|
|
|
```yaml
|
|
---
|
|
title: Examples # Required: navigation title
|
|
order: 6 # Required: sort order in navigation
|
|
redirect: <url> # Optional: redirect to this URL
|
|
hidden: true # Optional: hide from navigation
|
|
expand: true # Optional: expand sub-items in nav
|
|
ogImageUrl: <url> # Optional: open-graph thumbnail
|
|
---
|
|
```
|
|
|
|
### Previewing and updating the live site
|
|
|
|
PRs that touch `docs/content/` automatically get a Vercel preview deployment (link posted as a PR comment). For a full local preview, clone the [landing](https://github.com/rerun-io/landing) repo.
|
|
|
|
Production deploys from the `docs-latest` branch. Do not push to it directly.
|
|
|
|
- **Normal flow**: Merge to `main`. If the PR has the `deploy docs` label, the commit is automatically cherry-picked to `docs-latest` (via `.github/workflows/auto_docs.yml`), which triggers a Vercel redeploy.
|
|
- **Releases**: The release process force-pushes `main` to `docs-latest`.
|
|
- Any commits only on `docs-latest` (not on `main`) will be lost on the next release.
|
|
|
|
### Redirects
|
|
|
|
`docs/content/_redirects.yaml` maps old URLs to new locations. CI validates these via `scripts/ci/check_doc_redirects.py`. For redirects that should appear in navigation, use markdown files with `redirect` frontmatter instead.
|
|
|
|
## Type reference docs (auto-generated)
|
|
|
|
The files in `docs/content/reference/types/` are **generated by codegen** - do not edit them directly.
|
|
|
|
```
|
|
.fbs definitions → pixi run codegen → docs/content/reference/types/
|
|
(crates/store/re_sdk_types/ + Rust/Python/C++ SDK code
|
|
definitions/rerun/)
|
|
```
|
|
|
|
Documentation comes from `.fbs` file comments and attributes:
|
|
- `///` comments become the page description
|
|
- `\example archetypes/points3d_simple title="…" image="…"` embeds snippet examples
|
|
- `"attr.docs.category": "Spatial 3D"` groups types in index pages
|
|
- `"attr.docs.view_types": "Spatial3DView, Spatial2DView"` lists compatible views
|
|
|
|
The generator is at `crates/build/re_types_builder/src/codegen/docs/website.rs`.
|
|
|
|
## Code snippets
|
|
|
|
Multi-language code examples in `docs/snippets/all/`, organized by category:
|
|
|
|
```
|
|
docs/snippets/all/
|
|
archetypes/
|
|
points3d_simple.py # Snippet files are flat per category,
|
|
points3d_simple.rs # named {snippet_name}.{py,rs,cpp}
|
|
points3d_simple.cpp
|
|
howto/
|
|
load_urdf.py
|
|
tutorials/
|
|
data_out.py # Can have [section] markers for partial includes
|
|
views/
|
|
...
|
|
```
|
|
|
|
Reference in any doc page with a line containing only:
|
|
```
|
|
snippet: archetypes/points3d_simple
|
|
```
|
|
|
|
This renders a tabbed code block with all available languages. Snippets can also be referenced from `.fbs` files via `\example archetypes/points3d_simple title="…" image="…"`. Use `[section]` syntax to include only part of a snippet: `snippet: tutorials/data_out[imports]`.
|
|
|
|
Snippets are validated in CI via `docs/snippets/compare_snippet_output.py`, which builds and runs each snippet in all languages and compares their `.rrd` outputs.
|
|
|
|
### Screenshot links
|
|
|
|
Turn screenshots into links to the web viewer using `data-inline-viewer`:
|
|
|
|
```html
|
|
<picture data-inline-viewer="snippets/my-example">
|
|
<img src="https://static.rerun.io/my_screenshot/abc123/full.png">
|
|
</picture>
|
|
```
|
|
|
|
Values: `examples/{NAME}` for examples, `snippets/{NAME}` for snippets.
|
|
|
|
## API reference docs
|
|
|
|
### Python (`ref.rerun.io/docs/python/`)
|
|
|
|
Built with MkDocs (config: `rerun_py/mkdocs.yml`). The `gen-files` plugin runs `rerun_py/docs/gen_common_index.py` at build time to generate index pages from the `rerun` package structure using griffe.
|
|
|
|
Preview locally: `pixi run py-docs-serve`
|
|
|
|
See `rerun_py/docs/writing_docs.md` for docstring conventions.
|
|
|
|
### C++ (`ref.rerun.io/docs/cpp/`)
|
|
|
|
Built with Doxygen (config: `rerun_cpp/docs/Doxyfile`). Requires the `cpp` pixi environment.
|
|
|
|
Build locally: `pixi run -e cpp cpp-docs` (output at `rerun_cpp/docs/html/index.html`)
|
|
|
|
See `rerun_cpp/docs/writing_docs.md` for comment conventions.
|
|
|
|
### JS (`ref.rerun.io/docs/js/`)
|
|
|
|
Built with TypeDoc via Yarn workspaces.
|
|
|
|
Build locally: `pixi run js-docs` / `pixi run js-docs-serve`
|
|
|
|
### Deployment
|
|
|
|
API docs are built and uploaded to Google Cloud Storage (`gs://rerun-docs/docs/{python,cpp,js}/{version}/`) by `.github/workflows/reusable_deploy_docs.yml`. Each release creates a versioned copy and updates the `stable` alias.
|
|
|
|
## Search index
|
|
|
|
The search at `rerun.io/docs` is powered by Meilisearch. The index is built by `pixi run search-index build`, which ingests content from docs pages, Python/Rust API docs, and code examples. This runs in CI on pushes to `docs-latest` (see `.github/workflows/on_push_docs.yml`). It requires a nightly Rust toolchain for rustdoc JSON output.
|