Apache Kudu (incubating) 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
Table of Contents

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
Table of Contents

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
Table of Contents

In-Line Code or commands

monospace
Table of Contents

`text`

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

bold mono
Table of Contents

*`typethis`*

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

bold italic mono
Table of Contents

*_typesomething_*

Code blocks with highlighting

monospace, highlighted, preserve space
Table of Contents
[source,java]
----
  myAwesomeCode() {
}
----

Code block included from a separate file

included just as though it were part of the main file
Table of Contents
[source,ruby]
----
include::path/to/app.rb[]
----

Include only part of a separate file

Similar to Javadoc

File names, directory names, new terms

italic
Table of Contents

_hbase-default.xml_

External naked URLs

A link with the URL as link text
Table of Contents
http://www.google.com

External URLs with text

A link with arbitrary link text
Table of Contents
link:http://www.google.com[Google]

Create an internal anchor to cross-reference

not rendered
Table of Contents
[[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
Table of Contents
<<anchor_name>>

Cross-reference an existing anchor using custom text

an internal hyperlink using arbitrary text
Table of Contents
<<anchor_name,Anchor Text>>

A block image

The image with alt text
Table of Contents
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
Table of Contents
image:sunset.jpg [Alt Text]

(only one colon)

Link to a remote image

show an image hosted elsewhere
Table of Contents
image::http://inkscape.org/doc/examples/tux.svg[Tux,250,350]

(or image:)

Add dimensions or a URL to the image

depends
Table of Contents

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
Table of Contents
Some text.footnote:[The footnote text.]

A note or warning with no title

The admonition image followed by the admonition
Table of Contents
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
Table of Contents
.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
Table of Contents
* list item 1

(see http://asciidoctor.org/docs/user-manual/#unordered-lists)

Numbered lists

numbered list
Table of Contents
. list item 2

(see http://asciidoctor.org/docs/user-manual/#ordered-lists)

Checklists

Checked or unchecked boxes
Table of Contents

Checked:

- [*]

Unchecked:

- [ ]

Multiple levels of lists

bulleted or numbered or combo
Table of Contents
. 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
Table of Contents
Title:: content

Title::
  content

GUI menu cascades

bold text with arrows to show levels
Table of Contents

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
Table of Contents

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
Table of Contents
= 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
Table of Contents
include::[/path/to/file.adoc]

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

A table

a table
Table of Contents

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
Table of Contents

// This line won’t show up

Comment out a block

A section of the file is skipped during rendering
Table of Contents
////
Nothing between the slashes will show up.
////

Highlight text for review

text shows up with yellow background
Table of Contents
Test between #hash marks# is highlighted yellow.