Documentable provides you with an easy-to-use CLI application. This is useful if you only want to generate the static files as serve them with nginx or similar. It lets you customize the generation process with restrictions.

Options

documentable setup

Download template files in your current working directory. You can check them here. You do not need to use these exact files. You can modify them as you want, but take special care with the placeholders in main.mustache.

documentable start

Start the HTML generation process.

documentable update

Update the HTML files using the latest changes from the pod collection, without regenerate each and every file.

documentable clean

Delete the directories and files generated by documentable setup.

Parameters

--topdir=<Str>

Root directory where all your documentation is stored.

Default: "doc".

--conf=<Str>

Path to the configuration file (see configuration-file).

If a file named "documentable.json" is not found at the same directory where documentable was executed, the default configuration file will be used instead.

Default: "documentable.json".

This is the structure of this file:

{
  "title-page": "Raku Documentation",
  "pod-root-path": "https://github.com/Raku/doc/blob/master/doc",
  "irc-link": "https://webchat.freenode.net/?channels=#raku",
  "kinds": [
    {
      "kind": "language",
      "sort": "1",
      "display-text": "Language",
      "categories": [
        {
          "name": "beginning",
          "display-text": "At the beginning"
        },
        {
          "name": "migration",
          "display-text": "Migration guides"
        },
        {
          "name": "tutorial",
          "display-text": "Tutorials"
        },
        {
          "name": "fundamental",
          "display-text": "Fundamental topics"
        },
        {
          "name": "reference",
          "display-text": "General reference"
        },
        {
          "name": "advanced",
          "display-text": "Advanced topics"
        }
      ]
    },
    {
      "kind": "type",
      "display-text": "Types",
      "categories": [
        {
          "name": "basic",
          "display-text": "Basic"
        },
        {
          "name": "composite",
          "display-text": "Composite"
        },
        {
          "name": "domain-specific",
          "display-text": "Domain-specific"
        },
        {
          "name": "exception",
          "display-text": "Exceptions"
        }
      ]
    },
    {
      "kind": "routine",
      "display-text": "Routines",
      "categories": [
        {
          "name": "sub",
          "display-text": "Sub"
        },
        {
          "name": "method",
          "display-text": "Method"
        },
        {
          "name": "term",
          "display-text": "Term"
        },
        {
          "name": "operator",
          "display-text": "Operator"
        },
        {
          "name": "trait",
          "display-text": "Trait"
        },
        {
          "name": "submethod",
          "display-text": "Submethod"
        }
      ]
    },
    {
      "kind": "programs",
      "display-text": "Programs"
    }
  ]
}

The title-page will be the main headline of that page; pod-root-path will point to the default URL, and will be used mainly for substitution within pages; kinds are menus that will be inserted as part of the header, every kind will be a menu button. The categories section is used to generate different sub-menus in the header. The sort key tells Documentable to sort that specific page.

-v, --verbose

If True, progress information will be displayed.

Default: False.

-p, --primary

If True, HTML files associated with Documentable::Primary objects will be generated. That means, all your collection will be mapped to HTML, generating one HTML file by each pod block found.

Default: False.

-s, --secondary

If True, HTML files associated with Documentable::Secondary objects will be generated. Those files come from grouping those objects by name.

Default: False.

--search-index

If True, a search index will be generated to enable search capabilities in the site.

Default: False.

-i, --indexes

If True, index pages will be generated to group all HTML pages by Kinds and categories (see configuration-file).

Default: False.

-t, --typegraph

If True, TypeGraph representations will be generated (see typegraph) The representations will be cached when possible.

Default: False.

-f, --force

Force the generation of the TypeGraph representations (ignoring the cache).

Default: False.

--highlight

If True, block codes will be highlighted (see highlighting).

Default: False.

--typegraph-file=<Str>

Path to the TypeGraph file (see typegraph).

Default: "type-graph.txt".

--highlight-path=<Str>

Path to the directory containing the highlighter files. Internal use. This option should only be used from the docker container.

Default: "./highlights".

--dirs=<Str>

Comma separated values to specify the directories where documentable will look for documentation. Example: "--dirs=Language,Type".

Default: DOCUMENTABLE-DIRS.

-a, --all

Equivalent to specify -t -p -s -i --search-index

Default: DOCUMENTABLE-DIRS.

-o, --override

Always accept the operation (only available in 'documentable setup').

Default: False.

-V, --version

Version of Documentable.

Examples

If you only want to process your pod collection to check the pod files syntax. You can execute:

documentable start

Or maybe you only want to generate the primary files:

documentable start -p

Or the search index:

documentable start --search-index

And what if I have a different doc structure? For instance:

documentation
└── Potatoes
    ├── Potato1.pm6
└── Carrots
    ├── Carrot1.pm6

You only need to specify the correct dirs to Documentable:

documentable start --topdir=documentation --dirs=Potatoes,Carrots

The command used to generated the documentation for Documentable is:

documentable start --topdir=docs -v -a --highlight --highlight-path="/highlights"