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:

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.

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.com/[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.com/

Which renders like: http://neo4j.com/

	Note
	It’s ok to have a dot right after the URL, it won’t be part of the link.

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.

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!
////

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.

Figure 29.1. Hello World Graph

START n = node(Node[2])
RETURN n

Hello graphy world!

DocumentationTest.java

// 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: