autodoc

autodoc is a simple CI system optimized for document creation.

Quick Start Guide

Install Docker CE
Clone or download the autodoc repository, open a terminal inside the example_docs directory
Deploy an autodoc container:
```
docker run --rm -it \
  --name autodoc \
  --volume "${PWD}":/docs \
  --user "$(id -u):$(id -g)" \
  ldericher/autodoc
```
The contents of the directory are now being watched by autodoc!

When deploying an autodoc container, mount your document root to /docs. You should also set the container's UID and GID.
Edit some stuff, save, then watch the magic (and the terminal output)

Where not to use `autodoc`

autodoc is not a solution for Continuous Integration of large scale systems software! autodoc excels at building a large number of independent, small files.

Prime use case: Nextcloud

Nextcloud is a "safe home for all your data" that can easily be deployed using docker-compose.
Add an autodoc container to create directories where PDFs are automatically held up to date for all your documents. This extends upon the "Base version - apache" of the Nextcloud compose deployment.

version: '2'

volumes:
  documents:

services:
  app:
    volumes:
      - documents:/opt/autodoc

  autodoc:
    restart: always
    image: ldericher/autodoc
    user: "UID:GID"
    volumes:
      - documents:/docs

The "user" key should be set to the same numeric IDs used for the nextcloud worker processes! To find the right IDs, issue docker-compose exec app sh -c 'id -u www-data; id -g www-data'.
For the apache containers, this should evaluate to "33:33".

To begin, add the mounted /opt/autodoc as a local external storage to your Nextcloud instance.
You might need to setup the permissions on your new volume using docker-compose exec app chown -R www-data:www-data /opt/autodoc.

Basic functionality

autodoc uses inotifywait from inotify-tools to recursively watch a Linux file system directory.

For each file change, autodoc searches relevant build instruction files (Makefiles etc.) and kicks off build processes accordingly.

Concept: Source patterns

To avoid unnecessary rebuilds and self-triggering, autodoc uses "source patterns" to filter for the relevant build instructions.
A source pattern is a bash regular expression matching any filename that should be regarded as a "source file" to the build instruction file.

For instance, if a Makefile instructs how to build from Markdown source files, that Makefile's source pattern should likely be \.md$.

Creating an automated build

In general, just put your source files into any (sub-)directory watched by autodoc. Add a build instruction file.

On each file change, its containing directory is searched for a build instruction file. Watched parent directories are also probed for further build instructions.
Every relevant instruction file will be executed as found.

You may combine build instruction systems to your liking.

Build instruction systems

GNU Make (Makefiles)

autodoc supports standard Makefiles.
Makefiles must contain a SRCPAT annotation comment as follows, where <regex> is the source pattern as above.

#@SRCPAT <regex>

If there are multiple SRCPAT annotations, the lowermost one will be used.

Advanced Make options

You may add a PHONY target "autodoc" which will be built instead of the default target.

.PHONY: autodoc
autodoc:
  @echo "Hello World!"

3.8 KiB Raw Blame History