Homec4science
Diffusion Phabricator (feature/testing) Browse

phab/src/docs/userguide/diviner.diviner
a799a05b6cbcfeature/testing

Last Change
Raw File

diviner.diviner
View Options

@title Diviner User Guide
@group userguide
Using Diviner, a documentation generator.
= Overview =
NOTE: Diviner is new and not yet generally useful.
= Generating Documentation =
To generate documentation, run:
phabricator/ $ ./bin/diviner generate --book <book>
= .book Files =
Diviner documentation books are configured using JSON `.book` files, which
look like this:
name=example.book
{
"name" : "example",
"title" : "Example Documentation",
"short" : "Example Docs",
"root" : ".",
"uri.source" : "http://example.com/diffusion/X/browse/master/%f$%l",
"rules" : {
"(\\.diviner$)" : "DivinerArticleAtomizer"
},
"exclude" : [
"(^externals/)",
"(^scripts/)",
"(^support/)"
],
"groups" : {
"forward" : {
"name" : "Doing Stuff"
},
"reverse" : {
"name" : "Undoing Stuff"
}
}
}
The properties in this file are:
- `name`: Required. Short, unique name to identify the documentation book. This
will be used in URIs, so it should not have special characters. Good names
are things like `"example"` or `"libcabin"`.
- `root`: Required. The root directory (relative to the `.book` file) which
documentation should be generated from. Often this will be a value like
`"../../"`, to specify the project root (for example, if the `.book` file
is in `project/src/docs/example.book`, the value `"../../"` would generate
documentation from the `project/` directory.
- `title`: Optional. Full human-readable title of the documentation book. This
is used when there's plenty of display space and should completely describe
the book. Good titles are things like `"Example Documentation"`, or
`"libcabin Developer Documentation"`.
- `short`: Optional. Shorter version of the title for use when display space
is limited (for example, in navigation breadcrumbs). If omitted, the full
title is used. Good short titles are things like `"Example Docs"` or
`"libcabin Dev Docs"`.
- `uri.source`: Optional. Diviner can link from the documentation to a
repository browser so that you can quickly jump to the definition of a class
or function. To do this, it uses a URI pattern which you specify here.
Normally, this URI should point at a repository browser like Diffusion.
For example, `"http://repobrowser.yourcompany.com/%f#%l"`. You can use these
conversions in the URI, which will be replaced at runtime:
- `%f`: Replaced with the name of the file.
- `%l`: Replaced with the line number.
- `%%`: Replaced with a literal `%` symbol.
- `rules`: Optional. A map of regular expressions to Atomizer classes which
controls which documentation generator runs on each file. If omitted,
Diviner will use its default ruleset. For example, adding the key
`"(\\.diviner$)"` to the map with value `"DivinerArticleAtomizer"` tells
Diviner to analyze any file with a name ending in `.diviner` using the
"article" atomizer.
- `exclude`: Optional. A list of regular expressions matching paths which
will be excluded from documentation generation for this book. For example,
adding a pattern like `"(^externals/)"` or `"(^vendor/)"` will make Diviner
ignore those directories.
- `groups`: Optional. Describes top level organizational groups which atoms
should be placed into.
c4science · Help