Usage

Table of Contents

Start generator

Run ./generate_docs.sh. This will parse an process the config/repos.json project by project to generate single documentations and then it creates the index page.

Clone or update a repository

It clones/ pulls the configured repositories and generates static html pages with daux. Those repositories must have a “docs” subdirectory what can be generated to static files with Daux (see https://daux.io/).

All processed repositories will be cloned/ pulled in ./tmp/ directory.

.
:
├── tmp/
│  ├── [PROJECT_1]/                   << subir for docs of a repo
|  |   ├── docs/
|  |   ├── ...
|  |   └── ...
|  :
│  └── [PROJECT_N]/
:

Generate single documentations

If git made an update or the output dir of the project below public_html then a flag ist set to true to start the Daux converter for this project.

It starts daux generate and creates static html files below ./public_html/[project]

.
:
├── public_html/
│  └── [PROJECT]/                     << subir for docs of a repo
│     ├── daux_libraries/             << daux helper scripts
│     ├── daux_search_index.js        << data file for integrated search
│     ├── index.html                  << to html onverted md files in ./docs/
│     :
│     └── themes/                     << subdirs and files of used daux theme
:

Generate index

Additionally a ./public_html/index.html will be generated to get an overview page of all documentations. It uses the config/overview.template.

The final result is:

All files below ./public_html/ you can read offline (USB stick, CD ROM, …) or it can be copied to a webserver (it is not needed that it is in the webroot).

.
:
├── public_html/
│  ├── index.html                     << overvew page
│  :
│  ├── [PROJECT_1]/
│  :
│  └── [PROJECT_N]/
:

Customizing

File injection

In the config directory are 2 sub directories.

  • add_2_webroot - files hat will be synced into webroot public_html/
  • add_2_projects - files that will be synced to each public_html/[PROJECT_N]/

From the sync are excluded files matching to the file masks “*.sample.*” or “*.dist”.

With this mechanism you can add custom javascript or css files or images. Keep in mind to apply it it is needed to embed them into a template or inject lines to load css or javascript files. See next chapter.

Code injection

in the config/repos.json is an optional subkey “inject” that has subkeys to add html code

  • at the end of head or body on the index page
  • at the end of head or body of each html file generated by daux

As logn we use JSON that quotes a string with doublequotes you need to quote “ with a backslash

    ...
    "inject": {
        "idx_body": "<!-- script type=\"text/javascript\" src=\"functions.js\" defer=\"defer\"></script -->",
        "idx_head": "<!-- no inject idx_head -->",
        "doc_body": "<!-- script type=\"text/javascript\" src=\"/docs/functions.js\" defer=\"defer\"></script -->",
        "doc_head": "<!-- no inject doc_head -->"
    },
    ...

Cronjob

You should use a cronjob to regenerate all docs. Start ./generate_docs.sh in a cycle of your choice, eg. hourly.