Vyacheslav Egorov
b2d5245dcd
Main change is around removing our custom syntax which allows
to read markdown files directly on GitHub:
* instead of using custom link format `@{xref}` we start
using normal links. For example, [`dart::ThreadPool`][] is
understood as a ref to `dart::ThreadPool` class declaration.
`build.py` script injects an xref section at the end of
each markdown file.
* similarly we don't use custom syntax for admonitions, but
instead use blockquotes. `build.py` detects block quotes
which start with a marker like `**Note**` and renders
then in a custom way.
This CL also drops dependency on cquery and instead rewrites
indexing in pure Python via libclang.
Change-Id: I0b47ec93f632de89627a3c682d511c8b86c58430
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/280262
Reviewed-by: Martin Kustermann <kustermann@google.com>
Commit-Queue: Slava Egorov <vegorov@google.com>
47 lines
1.6 KiB
Markdown
47 lines
1.6 KiB
Markdown
This directory contains helper scripts for rendering runtime wiki pages as HTML.
|
|
|
|
```shell
|
|
# Run webserver for development.
|
|
$ runtime/tools/wiki/build/build.py
|
|
|
|
# Build wiki for deployment
|
|
$ runtime/tools/wiki/build/build.py --deploy
|
|
```
|
|
|
|
# Markdown extensions
|
|
|
|
## Admonitions and Asides
|
|
|
|
Blockquotes starting with `> **Marker**` are converted either:
|
|
|
|
- into sidenotes (if `Marker` is `Note`), which will be rendered on margins
|
|
of the page;
|
|
- admonitions (if `Marker` is `Source to read`, `Trying it` or `Warning`).
|
|
|
|
## Referencing C++ symbols and files
|
|
|
|
Script extends Markdown references with special support for references that
|
|
use ``[`ref`][]`` and ``[text][`ref`]``. The following values for `ref` are
|
|
recognized and resolved as links to GitHub at the current commit.
|
|
|
|
* `file-path` is resolved as a link to the given file;
|
|
* `package:name/path.dart` is resolved as a link to file `path.dart` within
|
|
package `name` - actual path is resolved via `.dart_tool/package_config.json`
|
|
file in the SDK root;
|
|
* `c++ symbol` is resolved as a link to the line in the file which defines
|
|
the given C++ symbol.
|
|
|
|
If markdown file contains any references in this form then running
|
|
`runtime/tools/wiki/build/build.py --deploy` will generate a reference
|
|
section at the end of the file. Appending this section allows other Markdown
|
|
tools (e.g. GitHub viewer) to render such special links correctly.
|
|
|
|
# Prerequisites
|
|
|
|
1. Install all Python dependencies.
|
|
```console
|
|
$ pip3 install coloredlogs jinja2 markdown aiohttp watchdog pymdown-extensions pygments
|
|
```
|
|
2. Install `libclang` (`brew install llvm` on Mac OS X).
|
|
3. Install SASS compiler (make sure that SASS binary is in your path).
|