recaptime.dev
@recaptime-dev's working patches + fork for Phorge, a community fork of Phabricator. (Upstream dev and stable branches are at upstream/main and upstream/stable respectively.)
hq.recaptime.dev/wiki/Phorge
phorge
phabricator
1@title Diviner User Guide
2@group userguide
3
4Using Diviner, a documentation generator.
5
6Overview
7========
8
9Diviner is an application for creating technical documentation.
10
11This article is maintained in a text file in the Phorge repository and
12generated into the display document you are currently reading using Diviner.
13
14Beyond generating articles, Diviner can also analyze source code and generate
15documentation about classes, methods, and other primitives.
16
17
18Generating Documentation
19========================
20
21To generate documentation, run:
22
23 phorge/ $ ./bin/diviner generate --book <book>
24
25
26Diviner ".book" Files
27=====================
28
29Diviner documentation books are configured using JSON `.book` files, which
30look like this:
31
32 name=example.book
33 {
34 "name" : "example",
35 "title" : "Example Documentation",
36 "short" : "Example Docs",
37 "root" : ".",
38 "uri.source" : "https://example.com/diffusion/X/browse/master/%f$%l",
39 "rules" : {
40 "(\\.diviner$)" : "DivinerArticleAtomizer"
41 },
42 "exclude" : [
43 "(^externals/)",
44 "(^scripts/)",
45 "(^support/)"
46 ],
47 "groups" : {
48 "forward" : {
49 "name" : "Doing Stuff"
50 },
51 "reverse" : {
52 "name" : "Undoing Stuff"
53 }
54 }
55 }
56
57The properties in this file are:
58
59 - `name`: Required. Short, unique name to identify the documentation book.
60 This will be used in URIs, so it should not have special characters. Good
61 names are things like `"example"` or `"libcabin"`.
62 - `root`: Required. The root directory (relative to the `.book` file) which
63 documentation should be generated from. Often this will be a value like
64 `"../../"`, to specify the project root (for example, if the `.book` file
65 is in `project/src/docs/example.book`, the value `"../../"` would generate
66 documentation from the `project/` directory.
67 - `title`: Optional. Full human-readable title of the documentation book. This
68 is used when there's plenty of display space and should completely describe
69 the book. Good titles are things like `"Example Documentation"`, or
70 `"libcabin Developer Documentation"`.
71 - `short`: Optional. Shorter version of the title for use when display space
72 is limited (for example, in navigation breadcrumbs). If omitted, the full
73 title is used. Good short titles are things like `"Example Docs"` or
74 `"libcabin Dev Docs"`.
75 - `uri.source`: Optional. Diviner can link from the documentation to a
76 repository browser so that you can quickly jump to the definition of a class
77 or function. To do this, it uses a URI pattern which you specify here.
78 Normally, this URI should point at a repository browser like Diffusion.
79 For example, `"https://repobrowser.example.com/%f#%l"`. You can use these
80 conversions in the URI, which will be replaced at runtime:
81 - `%f`: Replaced with the name of the file.
82 - `%l`: Replaced with the line number.
83 - `%%`: Replaced with a literal `%` symbol.
84 - `rules`: Optional. A map of regular expressions to Atomizer classes which
85 controls which documentation generator runs on each file. If omitted,
86 Diviner will use its default ruleset. For example, adding the key
87 `"(\\.diviner$)"` to the map with value `"DivinerArticleAtomizer"` tells
88 Diviner to analyze any file with a name ending in `.diviner` using the
89 "article" atomizer.
90 - `exclude`: Optional. A list of regular expressions matching paths which
91 will be excluded from documentation generation for this book. For example,
92 adding a pattern like `"(^externals/)"` or `"(^vendor/)"` will make Diviner
93 ignore those directories.
94 - `groups`: Optional. Describes top level organizational groups which atoms
95 should be placed into.