mirror of
https://we.phorge.it/source/phorge.git
synced 2024-11-15 03:12:41 +01:00
bcc082a01e
Summary:
- Complete the "project" -> "book" stuff. This is cleaner conceptually and keeps us from having yet another meaning for the word "project".
- Normalize symbols during atomization. This simplifies publishing a great deal, and allows static documentation to link to dynamic documentation and vice versa, because the canonical names of symbols are agreed upon (we can tweak the actual algorithm).
- Give articles a specifiable name distinct from the title, and default to something like "support" instead of "Get Help! Get Support!" so URIs end up more readable (not "Get_Help!_Get_Support!").
- Have the atomizers set book information on atoms.
- Implement very basic publishers. Publishers are basically glue code between the atomization process and the rendering process -- the two we'll have initially are "static" (publish to files on disk) and "phabricator" (or similar -- publish into the database).
- Handle duplicate symbol definitions in the atomize and publish pipelines. This fixes the issue where a project defines two functions named "idx()" and we currently tell them not to do that and break. Realistically, this is common in the real world and we should just roll our eyes and do the legwork to generate documentation as best we can.
- Particularly, dirty all atoms with the same name as a dirty atom (e.g., if 'function f()' is updated, regnerate the documentation for all functions named f() in the book).
- When publishing, we publish these at "function/f/@1", "function/f/@2". The base page will offer to disambiguate ("There are 8 functions named 'f' in this codebase, which one do you want?").
- Implement a very very basic renderer. This generates the actual HTML (or text, or XML, or whatever else) for the documentation, which the publisher dumps onto disk or into a database or whatever.
- The atomize workflow actually needs to depend on books, at least sort of, so make it load config and use it properly.
- Propagate multilevel dirties through the graph. If "C extends B" and "B extends A", we should regenerate C when A changes. Prior to this diff, we would regnerate B only.
Test Plan: Generated some documentation. Named two articles "feedback", generated docs, saw "article/feedback/@1/" and "article/feedback/@2/" created.
Reviewers: btrahan, vrana, chad
Reviewed By: chad
CC: aran
Maniphest Tasks: T988
Differential Revision: https://secure.phabricator.com/D4896
64 lines
1.8 KiB
PHP
64 lines
1.8 KiB
PHP
<?php
|
|
|
|
abstract class DivinerWorkflow extends PhutilArgumentWorkflow {
|
|
|
|
private $config;
|
|
private $bookConfigPath;
|
|
|
|
public function getBookConfigPath() {
|
|
return $this->bookConfigPath;
|
|
}
|
|
|
|
public function isExecutable() {
|
|
return true;
|
|
}
|
|
|
|
protected function getConfig($key, $default = null) {
|
|
return idx($this->config, $key, $default);
|
|
}
|
|
|
|
protected function getAllConfig() {
|
|
return $this->config;
|
|
}
|
|
|
|
protected function readBookConfiguration(PhutilArgumentParser $args) {
|
|
$book_path = $args->getArg('book');
|
|
if ($book_path === null) {
|
|
throw new PhutilArgumentUsageException(
|
|
"Specify a Diviner book configuration file with --book.");
|
|
}
|
|
|
|
$book_data = Filesystem::readFile($book_path);
|
|
$book = json_decode($book_data, true);
|
|
if (!is_array($book)) {
|
|
throw new PhutilArgumentUsageException(
|
|
"Book configuration '{$book_path}' is not in JSON format.");
|
|
}
|
|
|
|
// If the book specifies a "root", resolve it; otherwise, use the directory
|
|
// the book configuration file lives in.
|
|
$full_path = dirname(Filesystem::resolvePath($book_path));
|
|
if (empty($book['root'])) {
|
|
$book['root'] = '.';
|
|
}
|
|
$book['root'] = Filesystem::resolvePath($book['root'], $full_path);
|
|
|
|
// Make sure we have a valid book name.
|
|
if (!isset($book['name'])) {
|
|
throw new PhutilArgumentUsageException(
|
|
"Book configuration '{$book_path}' is missing required ".
|
|
"property 'name'.");
|
|
}
|
|
|
|
if (!preg_match('/^[a-z][a-z-]*$/', $book['name'])) {
|
|
$name = $book['name'];
|
|
throw new PhutilArgumentUsageException(
|
|
"Book configuration '{$book_path}' has name '{$name}', but book names ".
|
|
"must include only lowercase letters and hyphens.");
|
|
}
|
|
|
|
$this->bookConfigPath = $book_path;
|
|
$this->config = $book;
|
|
}
|
|
|
|
}
|