docmachine-cli/README.md

DocMachine (Utils)

DocMachine is a CLI 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

FIXME: list prerequisites for crystal lang & dependencies

Getting Started

Follow these steps to start using DocMachine:

Installation

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

Create a New Project

docmachine scaffold my-doc-project 

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

my-doc-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

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.

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 is licensed under the GPL-3.0-or-later license. See the LICENSE file for details.