Tooling to update code excerpts in Markdown documentation from regions declared in source files elsewhere.
Warning
This package is still a work-in-progress and not completely functional.
This package is not currently published on pub, so you must use it as a git or path dependency.
The package pulls content from Dart files that are optionally split up with code regions.
To include lines within a code region,
add a Dart line comment before the first line in the region with
#docregion <name>
where <name>
is your desired name for the region.
Then after the final line of the region,
add a Dart line comment with #enddocregion <name>
with the same name.
You can open and close a docregion multiple times within a file.
Region names must be a non-empty sequence of alphanumeric characters,
optionally containing dashes (-
).
A single docregion comment can open or close multiple regions with a comma-delimited list.
The following Dart snippet is an example of using docregion comments in a few different ways.
// #docregion imports
import 'dart:async';
// #enddocregion imports
// #docregion main, main-stub
void main() async {
// #enddocregion main-stub
print('Compute π using the Monte Carlo method.');
await for (final estimate in computePi().take(500)) {
print('π ≅ $estimate');
}
// #docregion main-stub
}
// #enddocregion main, main-stub
/// Generates a stream of increasingly accurate estimates of π.
Stream<double> computePi({int batch = 100000}) async* {
// ...
}
The regions defined in this Dart snippet are:
imports
, main
, main-stub
, and the unnamed region for the entire file.
Some of the regions defined in the example above include:
-
imports
region:import 'dart:async';
-
main-stub
region:void main() async { // ··· }
The main-stub
region is discontinuous as it has a break in it.
When this package is run to update excerpts, each break is
replaced by a language-specific comment filled with a plaster marker (...
).
For details concerning the processing of plasters, see the [code_excerpt_updater][] documentation.
To inject content from docregions or entire files into Markdown files, you use a special syntax to inject into a code block or configure the injecting logic.
In both cases, the syntax starts with \<?code-excerpt
and ends with ?>
.
Use an inject instruction to inject a docregion from a source file into the current Markdown file, with optional arguments to configure the injection.
Inject instructions must precede a Markdown code block that is denoted with the language in the target file.
<?code-excerpt "path/main.dart (optional-region-name)" arg0="value0" ...?>
```dart
void main() {}
```
The first unnamed argument, surrounded in double quotes, is the path to source file to pull regions from, relative to the base source path set by the CLI. A specific region from the file can be specified in parentheses, otherwise the entire file is extracted.
The following table outlines the parameters supported by injection instructions. Note that specified arguments, such as transformations, are applied in the order they appear in the instruction.
Parameter | Argument | Description |
---|---|---|
indent-by |
int |
The amount to indent each line by. |
plaster |
String |
The plaster template to use, or none to disable. |
skip |
int |
The amount of lines to skip at the beginning if positive, or end if negative. |
take |
int |
The amount of lines to take at the beginning if positive, or end if negative. |
remove |
String|RegExp |
Remove the lines containing the specified pattern. |
retain |
String|RegExp |
Keep the lines containing the specified pattern. |
from |
String|RegExp |
Keep the lines after and including the first one with the specified pattern. |
to |
String|RegExp |
Keep the lines before and including the first one with the specified pattern. |
replace |
Replacement syntax | Replace text with the specified pattern to the specified string. |
For parameters that accept a RegExp
,
they follow the Dart VM's supported syntax,
and must be wrapped in forward slashes, such as /<regexp>/
.
If you're passing a normal string, the forward slashes are unnecessary.
The replace
argument accepts one or more semicolon separated
regular expression and replacement expression pairs.
The replacement expressions can be simple strings or
include backreferences to numbered capture groups from the
regular expression using, $&
, $1
, $2
, and so on.
The following replace expression replaces text like Hello world
with [!Hello!] world
:
replace="/(Hello)( world)/[!$1!]$2/g;"
Compared to other transforms, replace transforms are applied on the entire excerpt rather than per line.
Use a set instruction to configure one of the following for subsequent injection instructions:
- The base directory that source files for docregions are found in.
- The template to be used for plaster lines.
- Replace expressions that will run for every inject instruction.
Only one set instruction argument can be used at a time, and only one of each can exist in the file. Subsequent set instructions of the same type override the previous ones.
To set the base directory that source files for docregions are found in
to a subdirectory of the CLI provided one, use the path-base
argument:
<?code-excerpt path-base="subdirPath"?>
To change the template used for plaster lines, use the plaster
argument:
<?code-excerpt plaster="// Fill in to complete."?>
If you want to use the default plaster content specified by the CLI,
you can use $defaultPlaster
within the template:
<?code-excerpt plaster="///// $defaultPlaster"?>
To add a transform expression that is applied to all subsequent excerpts
use the replace
argument and the same replacement syntax as above.
<?code-excerpt replace="/Hello/Hola/g;"?>
To reset any of the instructions,
use the same arguments set to an empty string (""
);
To update the excerpts specified by injection instructions
within your Markdown files, you can either use the package
as a library through the Updater
class, or the CLI.
dart run excerpter [OPTIONS] <file_or_directory>
Option | Description |
---|---|
--dry-run |
If the updater should only report if excerpts need to be updated. |
--fail-on-update |
Report a non-zero exit code if an excerpt is or needs to be updated. |
--exclude |
Regular expressions of paths to exclude when processing a directory recursively. Dot files and directories are always excluded. |
--base-source |
The path to the directory containing the source files that excerpt regions should be retrieved from. |
--plaster-content |
The default plaster content, such as "..." or "···". |
--replace |
A replacement to run on every excerpt. Refer to the replacement syntax for more details. |
To learn more about the tool, check out the various usages across the dart.dev and docs.flutter.dev website repositories.