106 lines
2.9 KiB
Markdown
106 lines
2.9 KiB
Markdown
|
# 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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
git clone https://code.apps.glenux.net/glenux/docmachine-utils.git docmachine-utils
|
||
|
|
cd docmachine-utils
|
||
|
|
make build
|
||
|
|
make install
|
||
|
|
```
|
||
|
|
|
||
|
|
### Create a New Project
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docmachine build -a build-slides-pdf
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash
|
||
|
|
docmachine build -a build-docs-pdf
|
||
|
|
```
|
||
|
|
|
||
|
|
```bash
|
||
|
|
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.
|
||
|
|
|