doc: add README.md
Some checks failed
continuous-integration/drone/push Build is failing

This commit is contained in:
Glenn Y. Rolland 2024-05-31 16:28:36 +02:00
parent e390e911af
commit e492cb4705

105
README.md Normal file
View file

@ -0,0 +1,105 @@
# 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.