@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
Add source links and a little documentation about Diviner
Summary: Ref T988. Links up the "Declared:" property to point at a repository browser, if one exists.
Test Plan: Viewed a class document, saw a link, clicked it, got the definition.
Reviewers: btrahan
Reviewed By: btrahan
CC: aran
Maniphest Tasks: T988
Differential Revision: https://secure.phabricator.com/D6820
+117
-5
+29
-5
src/applications/diviner/controller/DivinerAtomController.php
+29
-5
src/applications/diviner/controller/DivinerAtomController.php
···
100
100
$group_name = null;
101
101
}
102
102
103
-
$properties->addProperty(
104
-
pht('Defined'),
105
-
$atom->getFile().':'.$atom->getLine());
106
-
107
-
103
+
$this->buildDefined($properties, $symbol);
108
104
$this->buildExtendsAndImplements($properties, $symbol);
109
105
110
106
$warnings = $atom->getWarnings();
···
279
275
}
280
276
281
277
return $implements;
278
+
}
279
+
280
+
private function buildDefined(
281
+
PhabricatorPropertyListView $view,
282
+
DivinerLiveSymbol $symbol) {
283
+
284
+
$atom = $symbol->getAtom();
285
+
$defined = $atom->getFile().':'.$atom->getLine();
286
+
287
+
$link = $symbol->getBook()->getConfig('uri.source');
288
+
if ($link) {
289
+
$link = strtr(
290
+
$link,
291
+
array(
292
+
'%%' => '%',
293
+
'%f' => phutil_escape_uri($atom->getFile()),
294
+
'%l' => phutil_escape_uri($atom->getLine()),
295
+
));
296
+
$defined = phutil_tag(
297
+
'a',
298
+
array(
299
+
'href' => $link,
300
+
'target' => '_blank',
301
+
),
302
+
$defined);
303
+
}
304
+
305
+
$view->addProperty(pht('Defined'), $defined);
282
306
}
283
307
284
308
}
+2
src/docs/book/phabricator.book
+2
src/docs/book/phabricator.book
+2
src/docs/book/user.book
+2
src/docs/book/user.book
+84
src/docs/userguide/diviner.diviner
+84
src/docs/userguide/diviner.diviner
···
1
+
@title Diviner User Guide
2
+
@group userguide
3
+
4
+
Using Diviner, a documentation generator.
5
+
6
+
= Overview =
7
+
8
+
NOTE: Diviner is new and not yet generally useful.
9
+
10
+
= Generating Documentation =
11
+
12
+
To generate documentation, run:
13
+
14
+
phabricator/ $ ./bin/diviner generate --book <book>
15
+
16
+
= .book Files =
17
+
18
+
Diviner documentation books are configured using JSON `.book` files, which
19
+
look like this:
20
+
21
+
name=example.book
22
+
{
23
+
"name" : "example",
24
+
"title" : "Example Documentation",
25
+
"short" : "Example Docs",
26
+
"root" : ".",
27
+
"uri.source" : "http://example.com/diffusion/X/browse/master/%f$%l",
28
+
"rules" : {
29
+
"(\\.diviner$)" : "DivinerArticleAtomizer"
30
+
},
31
+
"exclude" : [
32
+
"(^externals/)",
33
+
"(^scripts/)",
34
+
"(^support/)"
35
+
],
36
+
"groups" : {
37
+
"forward" : {
38
+
"name" : "Doing Stuff"
39
+
},
40
+
"reverse" : {
41
+
"name" : "Undoing Stuff"
42
+
}
43
+
}
44
+
}
45
+
46
+
The properties in this file are:
47
+
48
+
- `name`: Required. Short, unique name to identify the documentation book. This
49
+
will be used in URIs, so it should not have special characters. Good names
50
+
are things like `"example"` or `"libcabin"`.
51
+
- `root`: Required. The root directory (relative to the `.book` file) which
52
+
documentation should be generated from. Often this will be a value like
53
+
`"../../"`, to specify the project root (for example, if the `.book` file
54
+
is in `project/src/docs/example.book`, the value `"../../"` would generate
55
+
documentation from the `project/` directory.
56
+
- `title`: Optional. Full human-readable title of the documentation book. This
57
+
is used when there's plenty of display space and should completely describe
58
+
the book. Good titles are things like `"Example Documentation"`, or
59
+
`"libcabin Developer Documentation"`.
60
+
- `short`: Optional. Shorter version of the title for use when display space
61
+
is limited (for example, in navigation breadcrumbs). If omitted, the full
62
+
title is used. Good short titles are things like `"Example Docs"` or
63
+
`"libcabin Dev Docs"`.
64
+
- `uri.source`: Optional. Diviner can link from the documentation to a
65
+
repository browser so that you can quickly jump to the definition of a class
66
+
or function. To do this, it uses a URI pattern which you specify here.
67
+
Normally, this URI should point at a repository browser like Diffusion.
68
+
For example, `"http://repobrowser.yourcompany.com/%f#%l"`. You can use these
69
+
conversions in the URI, which will be replaced at runtime:
70
+
- `%f`: Replaced with the name of the file.
71
+
- `%l`: Replaced with the line number.
72
+
- `%%`: Replaced with a literal `%` symbol.
73
+
- `rules`: Optional. A map of regular expressions to Atomizer classes which
74
+
controls which documentation generator runs on each file. If omitted,
75
+
Diviner will use its default ruleset. For example, adding the key
76
+
`"(\\.diviner$)"` to the map with value `"DivinerArticleAtomizer"` tells
77
+
Diviner to analyze any file with a name ending in `.diviner` using the
78
+
"article" atomizer.
79
+
- `exclude`: Optional. A list of regular expressions matching paths which
80
+
will be excluded from documentation generation for this book. For example,
81
+
adding a pattern like `"(^externals/)"` or `"(^vendor/)"` will make Diviner
82
+
ignore those directories.
83
+
- `groups`: Optional. Describes top level organizational groups which atoms
84
+
should be placed into.