From e492cb47058a8eb9398f003c0deb02c7f34e9082 Mon Sep 17 00:00:00 2001 From: "Glenn Y. Rolland" Date: Fri, 31 May 2024 16:28:36 +0200 Subject: [PATCH] doc: add README.md --- README.md | 105 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 105 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..2ffdd91 --- /dev/null +++ b/README.md @@ -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. +