mirror of
https://we.phorge.it/source/phorge.git
synced 2024-12-11 16:16:14 +01:00
464979302b
Summary: Fix a few "line too long" lint issues in the Diviner documentation. Also lint `*.book` files as JSON. Test Plan: Eye-ball it. Reviewers: epriestley, #blessed_reviewers Reviewed By: epriestley, #blessed_reviewers Subscribers: epriestley, Korvin Differential Revision: https://secure.phabricator.com/D9695
84 lines
3.3 KiB
Text
84 lines
3.3 KiB
Text
@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.
|