[Summary view] [Print] [Text view]

   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.
  49      This will be used in URIs, so it should not have special characters. Good
  50      names 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.