mirror of
https://github.com/ldericher/autodoc.git
synced 2025-12-06 15:43:01 +00:00
109 lines
4.6 KiB
Markdown
109 lines
4.6 KiB
Markdown
# autodoc
|
||
|
||
[`autodoc`](https://github.com/ldericher/autodoc) is a simple [CI](https://en.wikipedia.org/wiki/Continuous_integration) system optimized for document creation.
|
||
|
||
In general, any file-sharing solution – preferably on top of `docker-compose` – can be made into an automatic document distribution system by adding an `autodoc` instance.
|
||
|
||
## Quick Start Guide using Docker
|
||
|
||
The `autodoc` image [available on Docker Hub](https://hub.docker.com/r/ldericher/autodoc) is based on [pandocker](https://hub.docker.com/r/ldericher/pandocker) providing Ubuntu's TeXlive `LaTeX` and `pandoc` in a simple box.
|
||
|
||
01. Install [Docker CE](https://docs.docker.com/install/)
|
||
|
||
01. Clone or download the `autodoc` repository, open a terminal inside the [examples](https://github.com/ldericher/autodoc/tree/master/examples) directory
|
||
|
||
01. Deploy an `autodoc` container:
|
||
|
||
```bash
|
||
docker run --rm -it \
|
||
--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, just mount your document root to `/docs`. You *should* also set the container's UID and GID. These are seen above.
|
||
|
||
01. Edit some stuff, save – and watch the magic happen (and the terminal output).
|
||
|
||
On each file change, `autodoc` searches relevant build instruction files (Makefiles etc.) and kicks off build processes accordingly.
|
||
|
||
### How *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.
|
||
|
||
### Deploying without Docker
|
||
|
||
`autodoc` hard-depends only on `inotifywait`. Full dependencies are:
|
||
|
||
* [inotify-tools](https://github.com/rvoicilas/inotify-tools) to recursively watch Linux file system directories
|
||
* [GNU Make](https://www.gnu.org/software/make/) for plugin "make"
|
||
* A `LaTeX` distribution and [`pandoc`](https://pandoc.org/) for plugin "pandoc"
|
||
|
||
## Prime use case: Nextcloud
|
||
|
||
Nextcloud is a "safe home for all your data" that can [easily be deployed using docker-compose](https://hub.docker.com/_/nextcloud).
|
||
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](https://hub.docker.com/_/nextcloud#base-version---apache)" of the Nextcloud compose deployment.
|
||
|
||
```yaml
|
||
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 type' 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`.
|
||
|
||
## 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 GNU Makefiles.
|
||
However, Makefiles must contain a SRCPAT annotation comment as follows, where `<regex>` is a source pattern as above.
|
||
|
||
```Makefile
|
||
#%SRCPAT% <regex>
|
||
```
|
||
|
||
If there are multiple SRCPAT annotations, the lowermost one will be used.
|
||
|
||
You *may* add a PHONY target "autodoc" which will be built *instead* of the default target. This is demonstrated in [examples/automatic directory listing/a directory in space/Makefile](https://github.com/ldericher/autodoc/blob/develop/examples/automatic%20directory%20listing/a%20directory%20in%20space/Makefile).
|
||
|
||
```Makefile
|
||
.PHONY: autodoc
|
||
autodoc:
|
||
@echo "Hello World!"
|
||
```
|