1. Project

1.1. Description

Nowadays, projects hosted on GitHub often use a documentation-as-code, where documentation is written as text using formatting such as Markdown or Asciidoc.
AsciiDoc is used here because this formatting offers much higher flexibility and features than Markdown.
AsciiDoc is as simple as Markdown, for things that are doable in Markdown.

This Cookbook uses Asciidoctor is a fast text processor and publishing toolchain for converting AsciiDoc content to HTML5, EPUB3, PDF, DocBook 5

And for Confluence publishing, confluence-publisher allows, through a pre-defined set of folder structure to publish pages one-to-one with Confluence page hierarchical structure.

PlantUML is used to produce various diagrams from text, and Mingrammer python language for Architecture or deployment diagrams.

At last, few if/else are used (only at top of each adoc pages) to allow the documentation to be rendered on multiple targets:

  • GITHUB

  • PDF

  • HTML

  • Confluence

1.2. Tools

General tools enabling Doc-as-Code:

Writing text:

Diagrams:

Publishing

2. How-To

This chapter shows how to edit and publish documentation to the various destination mentioned above.

2.1. Pre-Requisits

Building the few docker image in this repository
$ make build

2.2. Editing

Using Visual Studio Code, install plugings such as AsciiDoc in order to render the .adoc files.

Follow syntax as documented in AsciiDoctor User Manual

2.3. Mingrammer Diagrams (standalone)

Mingrammer is tool of choice for architecture diagram as code.
Files are standard python files, easily understandable.

See example at assets-architecture-hla.py

Building assets is already part of next commands used to publish to PDF or Confluence.
However Mingrammer remains a standalone tool.
Building diagrams with mingrammer tool
# Create python assets under *src/main/adoc/assets* folder (e.g. assets-architecture-hla.py)
$ make doc.publishAssets

# PNG files will be available under *build/adoc/images* folder (e.g. assets-architecture-hla.png)
Example diagram

Diagram

2.4. Publishing

Building and Publishing the documentation can be done with targets:

  • Confluence

  • HTML

  • PDF Book

2.4.1. Editing/Publishing to PDF

Obviously, PDF are published in the form of Books while Confluence are set of Pages.
This make somewhat of a difference, but same doc can however be published to both targets.

Editing the documentation for publication to PDF

_SampleProject-Book.adoc holds the book, which is essentially a structured set of includes from the various adoc files used to publish to Confluence.

See Theming Guide
Building the documentation as PDF
$ make doc.publishToPDF

The published documentation PDF book will be found under build/_SampleProject-Book.pdf

2.4.2. Editing/Publishing to Confluence

This requires a Confluence instance, but thankfully a temporary instance can be started on localhost for testing.

Confluence start/stop/clean
$ confluence.start    # Wait a bit for this to settle !
$ confluence.logs
$ confluence.stop
$ confluence.clean

Confluence comes from https://github.com/confluence-publisher/confluence-publisher-it
This environment has a 3h timeframe license only for testing.

Confluence is available at http://localhost:8090

The following users are configured:
- admin/admin
- confluence-publisher-it/1234
Editing the documentation as Confluence

This is about editing the multiple adoc files starting from 00-Index.adoc, and recursively the folder with same name, etc
Each Confluence page is matching an adoc file, and title is the top first section.
Sub-pages are the recursive folder themselves holding other adoc files.

See Confluence Publisher GIT for details.

Setting up the target for publication

From current folder, edit the file named .env-confluence with your credentials. Don’t edit anything else.

ANCESTOR_ID is found by browsing Confluence page and clicking Edit button.
The Ancestor Id is the pageId seen in URL such as http://localhost:8090/pages/viewinfo.action?pageId=327706
Building the documentation as Confluence
$ make doc.publishToConfluence
The Confluence page will be found under the project page defined as ANCESTOR_ID.

3. Template

This page demonstrates some of what could be found in an Asciidoc documentation.

3.1. Images

Sample Mingrammer python diagram:

assets architecture hla

See How-To in Mingrammer Diagrams section for details.

3.2. Listing

This block is used to skip rendering.

= Document Title

3.3. Sources Block

This block is used to embed a chunk of file or code.

Source blocks are converted using the "code" macro. Only languages supported by the Code Block Macro can be used:
actionscript3, applescript, bash, c#, cpp, css, coldfusion, delphi, diff, erl, groovy,
xml, java, jfx, js, php, perl, text, powershell, py, ruby, sql, sass, scala,
vb, yml (since Confluence 6.7 only)

Example XML block:

pom.xml
<build>
  <plugins>
    <plugin>
      <groupId>org.sahli.asciidoc.confluence.publisher</groupId>
      <artifactId>asciidoc-confluence-publisher-maven-plugin</artifactId>
      <version><!-- insert version here --></version>
      <configuration>
        <asciidocRootFolder>etc/docs</asciidocRootFolder>
        <sourceEncoding>UTF-8<sourceEncoding> <!-- default -->
        <rootConfluenceUrl>http://localhost:8090</rootConfluenceUrl>
        <skipSslVerification>false</skipSslVerification>
        <spaceKey>SPACE</spaceKey>
        <ancestorId>327706</ancestorId>
        <username>username</username> <!-- or read from property -->
        <password>password</password> <!-- or read from property -->
        <pageTitlePrefix xml:space="preserve">Doc :: </pageTitlePrefix>
        <pageTitleSuffix xml:space="preserve"> [${project.version}]</pageTitleSuffix>
        <versionMessage>Version ${project.version}</versionMessage>
        <attributes>
            <version>${project.version}</version>
            <someOtherKey>value</someOtherKey>
        </attributes>
      </configuration>
    </plugin>
  </plugins>
</build>

Example Java block:

public class MyCode {
    // comment
}

3.4. Source Blocks from External Files (Full Content)

Including source code from external files is supported:

public class Source {
    // code from included source file
}

3.5. Source Blocks from External Files (Partial Content)

Restricting the source code to be included based on tags is supported:

    public void myMethod() {
        // method from included source file
    }

Other advanced features like listing file names or callouts are not supported.

3.6. Tables

Example simple Table:

Configuration Property Description Constraint

rootConfluenceUrl

The root URL of the Confluence instance to publish to.


Note: when publishing to Confluence Cloud, the root URL is https://<project>.atlassian.net/wiki.

mandatory

ancestorId

The id of the ancestor page under which the pages are appended.

Be aware that publishing will remove all pages under the configured ancestor id that are not part of the published
documentation ("orphaned pages").

mandatory

password

The password of the user to use for publishing.


Note: when publishing to Confluence Cloud, an API token generated via the corresponding Atlassian account has to
be used as password.

mandatory

publishingStrategy

The strategy to use when publishing to confluence. Possible values:

  • APPEND_TO_ANCESTOR: append the published pages to the ancestor and remove all orphaned pages

  • REPLACE_ANCESTOR: replace the title and the content of the ancestor with those of the one single root page and
    remove all orphaned pages (requires the documentation source structure to contain exactly one single root page)

optional (defaults to APPEND_TO_ANCESTOR)

3.7. Attachments

If an AsciiDoc file references a non-AsciiDoc file (e.g. a text file, PDF, …​) that non-AsciiDoc file is automatically added as an attachment to the corresponding Confluence page. Referenced non-AsciiDoc files are resolved relative to the location of the referencing AsciiDoc file.

Attachment links may specify a label.

3.8. Includes

Include files must be prefixed with an underscore.

 
This is content from included file

Links to content blocks within the same page are supported using AsciiDoc inline anchors and internal cross references:

Paragraph with inline anchor

Another paragraph with internal cross-reference to [paragraph-a]

Links to sections within the same page are supported either using anchors or custom section ids:

3.9.1. Section with Anchor

Paragraph with internal cross-reference to Section with Anchor

3.9.2. Section with Custom Id

Paragraph with internal cross-reference to Section with Custom Id

Links from one page to an inline anchor within another page are currently not supported.

3.10. Paragraphs

AsciiDoc paragraphs are translated to Confluence paragraphs, supporting all typical styles, for example:

This is a paragraph with bold text.

This is a paragraph with italic text.

This is a paragraph with monospaced text.

This is a paragraph with monospaced bold italic text.

This is a paragraph with superscript and subscript text.

This is the title of a paragraph

The title of a paragraph will rendered using a custom CSS class cp-paragraph-title

4. Diagrams

Here are diagrams which are automatically generated from text.

See PlantUML docs for details.

4.1. MindMap & Breakdown

MindMap Diagram
sample breakdown diagram

4.2. Network

sample network diagram

4.3. Activity diagram

Activity Diagram
sample actor diagram

4.4. Gant diagram

Gant Diagram

4.5. C4 diagrams

C4 Diagram

4.6. Relation diagram

sample relation diagram

4.7. UI diagram

sample ui diagram

4.8. Class diagram

Class Diagram
Class Diagram 2

4.9. Sequence diagram

Sequence Diagram
sample sequence diagram

4.10. Time diagram

sample time diagram

5. Cross-References

5.1. Examples

Examples of Doc As Code source repository and rendering below.

Not all are using AsciiDoc, however the principle remains the same with text source getting processed and rendered to different targets:

5.2. Demo

5.3. Diagrams

5.4. Applications & Tools

ASCIIDOC is tool of choice for all Designs, Architecture, Deployment Guides and User Guides.