DocMachine Cli

DocMachine Cli is a tool designed to simplify the process of creating technical documentation and presentations.

Motivation

This project aims to address the following challenges:

• Automation: Automate the generation of high-quality technical content, including documentation and presentation slides.
• Consistency: Ensure a consistent and polished look and feel across all content pieces.
• Efficiency: Reduce the time and effort required to produce content by leveraging AI tools.

Features

DocMachine offers a range of features to streamline the content creation process:

• Scaffolding: Generate a well-structured project directory with all the necessary files.
• Building: Compile and publish your content as HTML and PDF documents using Dockerized build processes.

We are actively developing the following features for future releases:

• Planning: Leverage LLMs (Large Language Models) to generate content outlines tailored to your specific needs and requirements.
• Writing: Utilize LLMs to draft content for each section and subsection, saving you valuable time and effort.

Prerequisites

You'll need a recent version of Crystal (>= 1.11.0) to use this project.

You'll also need to install a few dependencies:

• libreadline-dev
• libncurses-dev

Getting Started

Follow these steps to start using DocMachine Cli:

Installation

git clone https://code.apps.glenux.net/glenux/docmachine-cli.git docmachine-cli
cd docmachine-cli
make build
make install

Create a New Project

docmachine scaffold my-documentation-project

This command will create a new directory named my-documentation-project with the following structure:

my-documentation-project
├── _build
├── docs
│   └── images  # link to ../images
├── slides
│   └── images  # link to ../images
└── images

Start Writing Content

• Documentation: Place your Markdown files inside the docs directory.
• Presentations: Place your Markdown files (using Marp syntax) inside the slides directory.
• Images: Store your images in the respective images directories.

Live-reload during writing

docmachine build -a watch

By default DocMachine caches the container image archive under $XDG_CACHE_HOME/docmachine (or ~/.cache/docmachine). If you need to force a fresh download, run:

docmachine build --no-cache -a watch

This command will start a Docker container and build your documentation and presentations:

• Documentation: Built using MkDocs and served on http://localhost:5100.
• Presentations: Built using Marp and served on http://localhost:5200.

Building content for publishing or presentation

docmachine build -a build-slides-pdf

docmachine build -a build-docs-pdf

docmachine build -a build-docs-html

This command will generate the HTML and PDF versions of your content.

Testing and Specs

All automated tests live in the spec/ tree and are executed with crystal spec --error-trace (see CRUSH.md). Each top-level command (build, container, etc.) has its own folder so new specs sit next to the code they verify. For example, spec/build/run_spec.cr documents and tests cache behavior using a fake container engine, making it easy to understand how image caching should work. Add new specs beside the relevant command so the structure remains discoverable.

Contributing

We welcome contributions to DocMachine! To contribute:

1. Fork the repository.
2. Create a new branch for your feature or bug fix.
3. Make your changes and commit them.
4. Submit a pull request.

License

DocMachine Cli is licensed under the GPL-3.0-or-later license. See the LICENSE file for details.