1
0
Fork 0
mirror of https://we.phorge.it/source/phorge.git synced 2024-11-10 08:52:39 +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:
epriestley 2013-08-28 09:54:54 -07:00
parent 41ac06959e
commit a799a05b6c
4 changed files with 117 additions and 5 deletions

View file

@ -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);
}
}

View file

@ -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"
},

View file

@ -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"
},

View 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.