API Documentation

Earlier I used different Tools to create API Documentation out of the code and it's containing markdown format. But as I optimized it more and more may code got bloated with them.

Now I decided to put the documentation out of the code into it's own directory and files. As I had a look for good tools helping me to make it pretty displayable in the browser I decided to use GitBook.

1. GitBook

GitBook is an online platform for writing and hosting documentation using open source book format and toolchain. It has a big user base and can be integrated with GitHub and also working nearly as I did before using Markdown syntax.

See all my current books under https://www.gitbook.com/@alinex

1.1. General Usage

Firstly I had to install the GitHub Integrations Plugin within the GitBook options. Also the GitHub had to be allowed to use for GitBook.

Then I set up the repository by placing a book.json in it's root directory. It should at least contain the definition of the root directory used for the book. I need this because I store my documentation beside the code in its own directory.

{
  "root": "./doc"
}

Then you need the doc directory with the following files:

doc/README.md
doc/SUMMARY.de

The SUMMARY.de should contain your table of contents as bullet list with optional headings for chapters. This could look like:

# Summary

- [Introduction](README.md)
- [Alinex Project](alinex.md)

### Standards
- [Quality](quality.md)
- [Documentation](doc.md)
- [File Structure](filestructure.md)
- [Exit Codes](exitcodes.md)

### Modules
- [Alinex](modules.md)
- [3rd Party](3rd-party.md)

1.2. eBook Setup

To have a special cover on the PDF, ePub version of the book is done by providing two images:

cover.jpg
cover_small.jpg

A good cover should respect the following guidelines:

Size of 1800x2360 pixels for cover.jpg
Size of 200x262 pixels for cover_small.jpg
No border
Clearly visible book title
Any important text should be visible in the small version

And to set the layout you may use:

{
  "pdf": {
    "pageNumbers": true,
    "headerTemplate": " ",
    "footerTemplate": " "
  }
}

1.3. Writing Documentation

All the pages are written as single files in the doc folder using Markdown language. It is nearly the same as used on GitHub.

Attention: In contrast to the other markdown parsers there should be no space between the code tag and the language.

1.4. Plugins

1.4.1. Layout

To improve the layout of the book I use three different plugins:

{
  "plugins": ["toggle-chapters", "navigator", "downloadpdf"]
}

This will open/close chapters like folders, display a page navigation on the right side and a link to download as PDF on the top line.

To optimize the navigator output set the following in styles/ebook.css and styles/pdf.css to disable navigator:

#anchors-navbar, #goTop {display: none}

And for styles/website.css add this to optimize display and remove for small display:

#anchors-navbar {color: darkgray; right: 28px; top: 45px}
#goTop {display: none}
@media (max-width: 660px) {
  #anchors-navbar {display: none}
}

1.4.2. ToDo

As already used in GitHub markdown this plugin allows to write ToDo lists with check boxes which may be checked:

{
  "plugins": ["todo"]
}

Now you may create a checklist using:

Mercury
Venus
Earth (Orbit/Moon)
Mars
Jupiter
Saturn
Uranus
Neptune
Comet Haley

This is done using:

- [ ] Mercury
- [x] Venus
- [x] Earth (Orbit/Moon)
- [x] Mars
- [ ] Jupiter
- [ ] Saturn
- [ ] Uranus
- [ ] Neptune
- [ ] Comet Haley

1.4.3. Mermaid Graphs

Using Mermaid it is possible to include easy flowcharts without a specific program. It is written as plaintext and converted into chart on display.

To make this work the following plugin have to be defined:

{
  "plugins": ["mermaid-gb3"]
}

As an example this can look like:

graph TD; A-->B; A-->C; B-->D; C-->D;

This is done using:

```mermaid
graph TD;
  A-->B;
  A-->C;
  B-->D;
  C-->D;
```

1.4.4. PlantUML

PlantUML is another format to make graphs out of text descriptions like mermaid.

The plugin is loaded using:

{
  "plugins": ["puml"]
}

And the diagram may look like:

It is written using:

{% plantuml %}
Bob->Alice : hello
{% endplantuml %}

1.5. Final Setup

book.json

{
  "root": "./doc",

  "pdf": {
    "pageNumbers": true,
    "headerTemplate": " ",
    "footerTemplate": " "
  },

  "plugins": [
    "todo", "mermaid-gb3", "puml",
    "-highlight", "code-highlighter",
    "toggle-chapters", "navigator", "downloadpdf"
  ],
  "pluginsConfig": {
    "downloadpdf": {
      "base": "https://www.gitbook.com/download/pdf/book/alinex/nodejs",
      "label": "Download PDF",
      "multilingual": false
    }
  }
}

Further files

doc/README.md           # Introduction
doc/SUMMARY.md          # Page index of book
doc/cover.jpg           # eBook cover
doc/cover_small.jpg     # small cover
doc/styles/ebook.css    # user style
doc/styles/pdf.css      # user style
doc/styles/website.css  # user style

2. Internal API

The following tools may also be used to create automatic generated API documentation out of the code:

But keep in mind that it can never replace good hand written user manuals which concentrate mostly on the parts really used.

Documentation