mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-27 01:02:42 +01:00
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
This commit is contained in:
parent
41ac06959e
commit
a799a05b6c
4 changed files with 117 additions and 5 deletions
|
@ -100,11 +100,7 @@ final class DivinerAtomController extends DivinerController {
|
|||
$group_name = null;
|
||||
}
|
||||
|
||||
$properties->addProperty(
|
||||
pht('Defined'),
|
||||
$atom->getFile().':'.$atom->getLine());
|
||||
|
||||
|
||||
$this->buildDefined($properties, $symbol);
|
||||
$this->buildExtendsAndImplements($properties, $symbol);
|
||||
|
||||
$warnings = $atom->getWarnings();
|
||||
|
@ -281,4 +277,32 @@ final class DivinerAtomController extends DivinerController {
|
|||
return $implements;
|
||||
}
|
||||
|
||||
private function buildDefined(
|
||||
PhabricatorPropertyListView $view,
|
||||
DivinerLiveSymbol $symbol) {
|
||||
|
||||
$atom = $symbol->getAtom();
|
||||
$defined = $atom->getFile().':'.$atom->getLine();
|
||||
|
||||
$link = $symbol->getBook()->getConfig('uri.source');
|
||||
if ($link) {
|
||||
$link = strtr(
|
||||
$link,
|
||||
array(
|
||||
'%%' => '%',
|
||||
'%f' => phutil_escape_uri($atom->getFile()),
|
||||
'%l' => phutil_escape_uri($atom->getLine()),
|
||||
));
|
||||
$defined = phutil_tag(
|
||||
'a',
|
||||
array(
|
||||
'href' => $link,
|
||||
'target' => '_blank',
|
||||
),
|
||||
$defined);
|
||||
}
|
||||
|
||||
$view->addProperty(pht('Defined'), $defined);
|
||||
}
|
||||
|
||||
}
|
||||
|
|
|
@ -3,6 +3,8 @@
|
|||
"title" : "Phabricator Technical Documentation",
|
||||
"short" : "Phabricator Tech Docs",
|
||||
"root" : "../../../",
|
||||
"uri.source" :
|
||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
||||
"rules" : {
|
||||
"(\\.php$)" : "DivinerPHPAtomizer"
|
||||
},
|
||||
|
|
|
@ -3,6 +3,8 @@
|
|||
"title" : "Phabricator User Documentation",
|
||||
"short" : "Phabricator User Docs",
|
||||
"root" : "../../../",
|
||||
"uri.source" :
|
||||
"https://secure.phabricator.com/diffusion/P/browse/master/%f$%l",
|
||||
"rules" : {
|
||||
"(\\.diviner$)" : "DivinerArticleAtomizer"
|
||||
},
|
||||
|
|
84
src/docs/userguide/diviner.diviner
Normal file
84
src/docs/userguide/diviner.diviner
Normal file
|
@ -0,0 +1,84 @@
|
|||
@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.
|
Loading…
Reference in a new issue