Files

T

Vyacheslav Egorov b2d5245dcd [vm/docs] Improve VM docs tooling.

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>

2023-02-16 13:42:01 +00:00

1.6 KiB

Raw Permalink Blame History

This directory contains helper scripts for rendering runtime wiki pages as HTML.

# 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

Install all Python dependencies.

$ pip3 install coloredlogs jinja2 markdown aiohttp watchdog pymdown-extensions pygments

Install libclang (brew install llvm on Mac OS X).
Install SASS compiler (make sure that SASS binary is in your path).

1.6 KiB Raw Permalink Blame History

Markdown extensions

Admonitions and Asides

Referencing C++ symbols and files

Prerequisites

1.6 KiB

Raw Permalink Blame History