diviner.diviner
No OneTemporary
Actions

Size

3 KB

Referenced Files

None

Subscribers

None

diviner.diviner
View Options

	@title Diviner User Guide
	@group userguide

	Using Diviner, a documentation generator.

	Overview
	========

	Diviner is an application for creating technical documentation.

	This article is maintained in a text file in the Phorge repository and
	generated into the display document you are currently reading using Diviner.

	Beyond generating articles, Diviner can also analyze source code and generate
	documentation about classes, methods, and other primitives.


	Generating Documentation
	========================

	To generate documentation, run:

	phorge/ $ ./bin/diviner generate --book <book>


	Diviner ".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.

File Metadata

Mime Type: text/plain
Expires: Thu, Feb 6, 2:11 AM (15 h, 6 m)
Storage Engine: blob
Storage Format: Raw Data
Storage Handle: 33924
Default Alt Text: diviner.diviner (3 KB)

diviner.divinerNo OneTemporaryActions

diviner.divinerView Options

File Metadata

Event Timeline

diviner.diviner
No OneTemporary
Actions

diviner.diviner
View Options