The documents use the asciidoc format, see:
The cheatsheet is really useful!
You need to install asciidoc and docbook-xsl.
To generate the website locally use ./gradlew website. Output is in ~/manual/build/docs/website.
Each (sub)project has its own documentation, in src/docs/ and all the Asciidoc documents have the .txt file extension.
The documents can use code snippets which will extract code from the project. This is preferred way to include source code in the documentation, since any refactoring will be reflected in the documentation.
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.
The whole documentation set is generated from the *manual* module in the SDK, and we are currently only creating the website. The User Guide and Reference Manual are future projects.
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 produce warnings, or even fail (depending on severity), the build.
This is how a document should start:
[[unique-id-verbose-is-ok,Remember This Caption]] = 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.
Try to put one sentence on each line. Lines without empty lines between them still belongs to the same paragraph. 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: Documentation Flow
Just write "see <<target-id>>" and similar, that’s enough 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>>
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:
https://polygene.apache.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:
https://polygene.apache.org/
Which renders like: https://polygene.apache.org/
It’s ok to have a dot right after the URL, it won’t be part of the link.
https://polygene.apache.org/.
Which renders like: https://polygene.apache.org/.
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.
Tip.
Important
Caution
Warning
Here’s how it’s done:
NOTE: Note.
A multiline variation:
[TIP] Tiptext. Line 2.
Which is rendered as:
Tiptext. Line 2.
All images in the entire manual share the same namespace.
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::logo-standard.png[]
Which is rendered as:
Please note that the images/ directory is added automatically and not part of the link.
There are also global resources, residing in manual/src/resources, which will be copied to the root of the documentation.
Most source code that is included in the documentation should be extract via SNIPPET markers and then included in document with;
[snippet,java] ----------- source=tutorials/introduction/tenminutes/src/main/java/org/apache/polygene/demo/tenminute/OrderEntity.java tag=mainClass -----------
The source file is relative to the SDK root, and the tag is defined in the source file. The above could be bringing in content that looks like;
package org.apache.polygene.demo.tenminute;
import org.apache.polygene.api.concern.Concerns;
import org.apache.polygene.api.entity.EntityComposite;
import org.apache.polygene.api.sideeffect.SideEffects;
// START SNIPPET: sideEffect
@SideEffects( MailNotifySideEffect.class )
// START SNIPPET: mainClass
@Concerns({PurchaseLimitConcern.class, InventoryConcern.class})
public interface OrderEntity
extends Order, HasSequenceNumber, HasCustomer,
HasLineItems, Confirmable, EntityComposite
{
// END SNIPPET: sideEffect
}
// END SNIPPET: mainClasswhich will be rendered as;
@Concerns( { PurchaseLimitConcern.class, InventoryConcern.class } )
public interface OrderEntity
extends Order, Confirmable,
HasSequenceNumber, HasCustomer, HasLineItems,
HasIdentity
{
}
Note that 1. The START and END doesn’t need to be matching. 1. The AsciiDoc plugin will remove the START SNIPPET and END SNIPPET lines. 1. If you have more than one START/END section with the same tag, the plugin will insert a "[…snip…]" for the excluded lines.
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,java]
----
HashMap<String,String> result = new HashMap<String,String>();
for( String name : names )
{
if( !"".equals( name ) )
result.put( name, value );
}
----Which is rendered as:
HashMap<String,String> result = new HashMap<String,String>();
for( String name : names )
{
if( !"".equals( name ) )
result.put( name, value );
}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/.
Common attributes you can use in documents:
These can substitute part of URLs that point to for example APIdocs or source code.
Useful links when configuring the docbook toolchain: