Kudu Documentation Style Guide

This document gives you the information you need to get started contributing to Kudu documentation. For code contribution guidelines, see Contributing to Kudu.

Asciidoc

Kudu documentation is written in Asciidoc and compiled into HTML and output using the Asciidoctor toolchain. This provides several advantages. Among them:

  • Asciidoc is a superset of Markdown, so if you already know Markdown you can get started right away.

  • Github includes support for Asciidoc in its Atom editor, as well as real-time simplified HTML rendering.

  • Patch submissions are small and easy to review.

Code Standards

Within reason, try to adhere to these standards:

  • 100 or fewer columns per line

  • 2 spaces rather than tabs for indentation

  • No more than 4 nested levels in the documentation if possible: (Document → Chapter → Section → Subsection)

  • When possible, provide the language that a code listing is in, using the [source,<language>] macro. for example, [source,sql]

  • In general, do not indent Asciidoc, as indentation is significant. Code listings are one exception.

Building Documentation

To build the documentation locally, you need the Asciidoctor Ruby application. To build the entire Kudu documentation set, change to the docs/ directory and run:

asciidoctor -d book -D docs *.adoc

This builds the HTML output in a new docs/ directory within the current directory. Some content, such as the per-daemon configuration reference files, is not populated during a local build.

To view the HTML, open docs/index.html in your local browser.

You can also build only a single chapter. such as introduction.adoc, by passing its name instead.

Asciidoc Style Guide

Asciidoc supports a lot of syntax that we do not need to use. When possible, stick with the following, adapted from the HBase Reference Guide:

Table 1. AsciiDoc Cheat Sheet
Element Type Desired Rendering How to do it

A paragraph

a paragraph

Just type some text with a blank line at the top and bottom.

Add line breaks within a paragraph without adding blank lines

Manual line breaks

This will break + at the plus sign. Or prefix the whole paragraph with a line containing '[%hardbreaks]'

Give a title to anything

Colored italic bold differently-sized text

In-Line Code or commands

monospace

`text`

In-line literal content (things to be typed exactly as shown)

bold mono

*`typethis`*

In-line replaceable content (things to substitute with your own values)

bold italic mono

*_typesomething_*

Code blocks with highlighting

monospace, highlighted, preserve space

 
[source,java]
----
  myAwesomeCode() {
}
----

Code block included from a separate file

included just as though it were part of the main file

 
[source,ruby]
----
include::path/to/app.rb[]
----

Include only part of a separate file

Similar to Javadoc

File names, directory names, new terms

italic

_hbase-default.xml_

External naked URLs

A link with the URL as link text

 
http://www.google.com

External URLs with text

A link with arbitrary link text

 
link:http://www.google.com[Google]

Create an internal anchor to cross-reference

not rendered

 
[[anchor_name]]

Cross-reference an existing anchor using its default title

an internal hyperlink using the element title if available, otherwise using the anchor name

 
<<anchor_name>>

Cross-reference an existing anchor using custom text

an internal hyperlink using arbitrary text

 
<<anchor_name,Anchor Text>>

A block image

The image with alt text

 
image::sunset.jpg[Alt Text]

(put the image in the src/main/site/resources/images directory)

An inline image

The image with alt text, as part of the text flow

 
image:sunset.jpg [Alt Text]

(only one colon)

Link to a remote image

show an image hosted elsewhere

 
image::http://inkscape.org/doc/examples/tux.svg[Tux,250,350]

(or image:)

Add dimensions or a URL to the image

depends

inside the brackets after the alt text, specify width, height and/or link="http://my_link.com"

A footnote

subscript link which takes you to the footnote

 
Some text.footnote:[The footnote text.]

A note or warning with no title

The admonition image followed by the admonition

 
NOTE: My note here
WARNING: My warning here

A complex note

The note has a title and/or multiple paragraphs and/or code blocks or lists, etc

 
.The Title
[NOTE]
====
Here is the note text.
Everything until the second set of four equals signs
is part of the note.
----
some source code
----
====

Bullet lists

bullet lists

Numbered lists

numbered list

Checklists

Checked or unchecked boxes

Checked:

- [*]

Unchecked:

- [ ]

Multiple levels of lists

bulleted or numbered or combo

 
. Numbered (1), at top level
* Bullet (2), nested under 1
* Bullet (3), nested under 1
. Numbered (4), at top level
* Bullet (5), nested under 4
** Bullet (6), nested under 5
- [x] Checked (7), at top level

Labelled lists / variablelists

a list item title or summary followed by content

 
Title:: content

Title::
  content

GUI menu cascades

bold text with arrows to show levels

Use an ASCII arrow.

*File -> Print*

renders like File → Print

Sidebars, quotes, or other blocks of text

a block of text, formatted differently from the default

Delimited using different delimiters, see http://asciidoctor.org/docs/user-manual/#built-in-blocks-summary. Some of the examples above use delimiters like ...., ----,====.

[example]
====
This is an example block.
====

[source]
----
This is a source block.
----

[note]
====
This is a note block.
====

[quote]
____
This is a quote block.
____

If you want to insert literal Asciidoc content that keeps being interpreted, when in doubt, use eight dots as the delimiter at the top and bottom.

Nested Sections

chapter, section, sub-section, etc

 
= Book (or chapter if the chapter can be built alone, see leveloffset below)

== Chapter (or section if the chapter is standalone)

=== Section (or subsection, etc)

==== Subsection

and so on up to 6 levels (think carefully about going deeper than 4 levels, maybe you can just titled paragraphs or lists instead). Note that you can include a book inside another book by adding the :leveloffset:+1 macro directive directly before your include, and resetting it to 0 directly after. See the book.adoc source for examples, as this is how this guide handles chapters. Don’t do it for prefaces, glossaries, appendixes, or other special types of chapters.

Include one file from another

Content is included as though it were inline

 
include::[/path/to/file.adoc]

For plenty of examples. see docs/docs.adoc.

A table

a table

See http://asciidoctor.org/docs/user-manual/#tables. Generally rows are separated by newlines and columns by pipes

Comment out a single line

A line is skipped during rendering

// This line won’t show up

Comment out a block

A section of the file is skipped during rendering

 
////
Nothing between the slashes will show up.
////

Highlight text for review

text shows up with yellow background

 
Test between #hash marks# is highlighted yellow.