Note | |
---|---|
Other than writing documentation, you can help out by providing comments - head over to the online HTML version to do that! |
For how to build the manual see: readme
The documents use the asciidoc format, see:
The cheatsheet is really useful!
Each (sub)project has its own documentation, which will produce a docs.jar file.
By default this file is assembled from the contents in src/docs/.
Asciidoc documents have the .txt
file extension.
The documents can use code snippets which will extract code from the project. The corresponding code must be deployed to the sources.jar or test-sources.jar file.
By setting up a unit test accordingly, documentation can be written directly in the JavaDoc comment.
The above files are all consumed by the build of the manual (by adding them as dependencies). To get content included in the manual, it has to be explicitly included by a document in the manual as well.
Note that different ways to add documentation works best for different cases:
.txt
file containing the text.
Source snippets and output examples can then be included from there.
In this case you typically want to link to the source code, and users should be able to run it without any special setup.
Directory | Contents |
---|---|
dev/ | content aimed at developers |
dev/images/ | images used by the dev docs |
ops/ | content aimed at operations |
ops/images/ | images used by the ops docs |
man/ | manpages |
Additional subdirectories are used as needed to structure the documents, like dev/tutorial/, ops/tutorial/ etc.
Each document starts over with headings from level zero (the document title). Each document should have an id. In some cases sections in the document need to have id’s as well, this depends on where they fit in the overall structure. To be able to link to content, it has to have an id. Missing id’s in mandatory places will fail the build.
This is how a document should start:
[[unique-id-verbose-is-ok]] The Document Title ==================
To push the headings down to the right level in the output, the leveloffset
attribute is used when including the document inside of another document.
Subsequent headings in a document should use the following syntax:
== Subheading == ... content here ... === Subsubheading === content here ...
Asciidoc comes with one more syntax for headings, but in this project it’s not used.
Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences.
=
as there are characters in the title.
{}
are used for Asciidoc attributes, everything inside will be treated as an attribute.
What you have to do is to escape the opening brace: \{
.
If you don’t, the braces and the text inside them will be removed without any warning being issued!
To link to other parts of the manual the id of the target is used. This is how such a reference looks:
<<community-docs-overall-flow>>
Which will render like: Section 29.2.1, “Overall Flow”
Note | |
---|---|
Just write "see <<target-id>>" and similar, that should suffice in most cases. |
If you need to link to another document with your own link text, this is what to do:
<<target-id, link text that fits in the context>>
Note | |
---|---|
Having lots of linked text may work well in a web context but is a pain in print, and we aim for both! |
External links are added like this:
http://neo4j.org/[Link text here]
Which renders like: Link text here
For short links it may be better not to add a link text, just do:
http://neo4j.org/
Which renders like: http://neo4j.org/
Note | |
---|---|
It’s ok to have a dot right after the URL, it won’t be part of the link. |
methodName()
and is used for literals as well
command
(typically used for command-line)
These are very useful and should be used where appropriate. Choose from the following (write all caps and no, we can’t easily add new ones):
Note | |
---|---|
Note. |
Tip | |
---|---|
Tip. |
Important | |
---|---|
Important |
Caution | |
---|---|
Caution |
Warning | |
---|---|
Warning |
Here’s how it’s done:
NOTE: Note.
A multiline variation:
[TIP] Tiptext. Line 2.
Which is rendered as:
Tip | |
---|---|
Tiptext. Line 2. |
Important | |
---|---|
All images in the entire manual share the same namespace. You know how to handle that. |
To include an image file, make sure it resides in the images/ directory relative to the document you’re including it from. Then go:
image::neo4j-logo.png[]
Which is rendered as:
We use the Graphviz/DOT language to describe graphs. For documentation see http://graphviz.org/.
This is how to include a simple example graph:
["dot", "community-docs-graphdb-rels.svg"] ---- "Start node" -> "End node" [label="relationship"] ----
Which is rendered as:
Here’s an example using some predefined variables available in the build:
["dot", "community-docs-graphdb-rels-overview.svg", "meta"] ---- "A Relationship" [fillcolor="NODEHIGHLIGHT"] "Start node" [fillcolor="NODE2HIGHLIGHT"] "A Relationship" -> "Start node" [label="has a"] "A Relationship" -> "End node" [label="has a"] "A Relationship" -> "Relationship type" [label="has a"] Name [TEXTNODE] "Relationship type" -> Name [label="uniquely identified by" color="EDGEHIGHLIGHT" fontcolor="EDGEHIGHLIGHT"] ----
Which is rendered as:
The optional second argument given to the dot filter defines the style to use:
neoviz
: Nodespace view generated by Neoviz.
meta
: Graphs that don’t resemble db contents, but rather concepts.
Caution | |
---|---|
Keywords of the DOT language have to be surrounded by double quotes when used for other purposes. The keywords include node, edge, graph, digraph, subgraph, and strict. |
Common attributes you can use in documents:
These can substitute part of URLs that point to for example APIdocs or source code. Note that neo4j-git-tag also handles the case of snapshot/master.
Sample Asciidoc attributes which can be used:
There’s a separate build including comments.
The comments show up with a yellow background.
This build doesn’t run by default, but after a normal build, you can use make annotated
to build it.
You can also use the resulting page to search for content, as the full manual is on a single page.
Here’s how to write a comment:
// this is a comment
The comments are not visible in the normal build. Comment blocks won’t be included in the output of any build at all. Here’s a comment block:
//// Note that includes in here will still be processed, but not make it into the output. That is, missing includes here will still break the build! ////
Warning | |
---|---|
Use this kind of code snippets as little as possible. They are well known to get out of sync with reality after a while. |
This is how to do it:
[source,cypher] ---- start n=(2, 1) where (n.age < 30 and n.name = "Tobias") or not(n.name = "Tobias") return n ----
Which is rendered as:
start n=(2, 1) where (n.age < 30 and n.name = "Tobias") or not(n.name = "Tobias") return n
If there’s no suitable syntax highlighter, just omit the language: [source]
.
Currently the following syntax highlighters are enabled:
For other highlighters we could add see http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/.
Code can be automatically fetched from source files. You need to define:
artifactId
of the Maven coordinates,
sources
or test-sources
or any other classifier pointing to the artifact,
Note that the artifact has to be included as a Maven dependency of the Manual project so that the files can be found.
Be aware of that the tag "abc" will match "abcd" as well. It’s a simple on/off switch, meaning that multiple occurrences will be assembled into a single code snippet in the output. This behavior can be user to hide away assertions from code examples sourced from tests.
This is how to define a code snippet inclusion:
[snippet,java] ---- component=neo4j-examples source=org/neo4j/examples/HelloWorldTest.java classifier=test-sources tag=startDb ----
This is how it renders:
GraphDatabaseService graphDb = new EmbeddedGraphDatabase( DB_PATH ); registerShutdownHook( graphDb );
There’s a special filter for Cypher query results. This is how to tag a query result:
.Result [queryresult] ---- +----------------------------------+ | friend_of_friend.name | count(*) | +----------------------------------+ | Ian | 2 | | Derrick | 1 | | Jill | 1 | +----------------------------------+ 3 rows, 12 ms ----
This is how it renders:
For Java, there are a couple of premade utilities that keep code and documentation together in Javadocs and code snippets that generate Asciidoc for the rest of the toolchain.
To illustrate this, look at the following documentation that generates the Asciidoc file hello-world-title.txt
with a content of:
[[examples-hello-world-sample-chapter]] Hello world Sample Chapter ========================== This is a sample documentation test, demonstrating different ways of bringing code and other artifacts into Asciidoc form. The title of the generated document is determined from the method name, replacing "+_+" with " ". Below you see a number of different ways to generate text from source, inserting it into the JavaDoc documentation (really being Asciidoc markup) via the +@@+ snippet markers and programmatic adding with runtime data in the Java code. - The annotated graph as http://www.graphviz.org/[GraphViz]-generated visualization: .Hello World Graph ["dot", "Hello-World-Graph-hello-world-Sample-Chapter.svg", "neoviz"] ---- N1 [ label = "{Node\[1\]|'name' = 'you' : String\l}" ] N2 [ label = "{Node\[2\]|'name' = 'I' : String\l}" ] N2 -> N1 [ label = "know\n" ] ---- - A sample Cypher query: [source,cypher] ---- START n = node(Node[2]) RETURN n ---- - A sample text output snippet: [source] ---- Hello graphy world! ---- - a generated source link to the original GIThub source for this test: https://github.com/neo4j/community/blob/{neo4j-git-tag}/embedded-examples/src/test/java/org/neo4j/examples/DocumentationTest.java[DocumentationTest.java] - The full source for this example as a source snippet, highlighted as Java code: [snippet,java] ---- component=neo4j-examples source=org/neo4j/examples/DocumentationTest.java classifier=test-sources tag=sampleDocumentation ---- This is the end of this chapter.
this file is included in this documentation via
:leveloffset: 3 include::{importdir}/neo4j-examples-docs-jar/dev/examples/hello-world-sample-chapter.txt[]
which renders the following chapter:
This is a sample documentation test, demonstrating different ways of
bringing code and other artifacts into Asciidoc form. The title of the
generated document is determined from the method name, replacing "_
" with
" ".
Below you see a number of different ways to generate text from source,
inserting it into the JavaDoc documentation (really being Asciidoc markup)
via the @@
snippet markers and programmatic adding with runtime data
in the Java code.
START n = node(Node[2]) RETURN n
Hello graphy world!
// START SNIPPET: _sampleDocumentation package org.neo4j.examples; import static org.neo4j.visualization.asciidoc.AsciidocHelper.createCypherSnippet; import static org.neo4j.visualization.asciidoc.AsciidocHelper.createGraphViz; import static org.neo4j.visualization.asciidoc.AsciidocHelper.createOutputSnippet; import org.junit.Test; import org.neo4j.kernel.impl.annotations.Documented; import org.neo4j.test.GraphDescription.Graph; public class DocumentationTest extends AbstractJavaDocTestbase { /** * This is a sample documentation test, demonstrating different ways of * bringing code and other artifacts into Asciidoc form. The title of the * generated document is determined from the method name, replacing "+_+" with * " ". * * Below you see a number of different ways to generate text from source, * inserting it into the JavaDoc documentation (really being Asciidoc markup) * via the +@@+ snippet markers and programmatic adding with runtime data * in the Java code. * * - The annotated graph as http://www.graphviz.org/[GraphViz]-generated visualization: * * @@graph * * - A sample Cypher query: * * @@cypher * * - A sample text output snippet: * * @@output * * - a generated source link to the original GIThub source for this test: * * @@github * * - The full source for this example as a source snippet, highlighted as Java code: * * @@sampleDocumentation * * This is the end of this chapter. */ @Test // signaling this to be a documentation test @Documented // the graph data setup as simple statements @Graph( "I know you" ) // title is determined from the method name public void hello_world_Sample_Chapter() { // initialize the graph with the annotation data data.get(); gen.get().addSourceSnippets( this.getClass(), "sampleDocumentation" ); gen.get().addGithubLink( "github", this.getClass(), "neo4j/community", "embedded-examples" ); gen.get().addSnippet( "output", createOutputSnippet( "Hello graphy world!" ) ); gen.get().addSnippet( "graph", createGraphViz( "Hello World Graph", graphdb(), gen.get().getTitle() ) ); // A cypher snippet referring to the generated graph in the start clause gen.get().addSnippet( "cypher", createCypherSnippet( "start n = node(" + data.get().get( "I" ) + ") return n" ) ); } } // END SNIPPET: _sampleDocumentation
This is the end of this chapter.
Useful links when configuring the docbook toolchain:
Copyright © 2012 Neo Technology