Compare commits

..

3 commits

Author SHA1 Message Date
62cdbdb089 docs: add missing information to README
All checks were successful
continuous-integration/drone/push Build is passing
2024-06-02 21:21:50 +02:00
0d4db95186 Merge branch 'develop' of code.apps.glenux.net:glenux/docmachine-cli into develop
All checks were successful
continuous-integration/drone/push Build is passing
2024-06-02 21:14:03 +02:00
6f316ff78e refactor: move static network functions to a reusable class 2024-06-02 21:13:36 +02:00
3 changed files with 57 additions and 38 deletions

View file

@ -1,40 +1,53 @@
# DocMachine (Utils)
# DocMachine Cli
DocMachine is a CLI tool designed to simplify the process of creating technical documentation and presentations.
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.
* **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.
* **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.
* **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
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:
Follow these steps to start using DocMachine Cli:
### Installation
```bash
git clone https://code.apps.glenux.net/glenux/docmachine-utils.git docmachine-utils
cd docmachine-utils
git clone https://code.apps.glenux.net/glenux/docmachine-cli.git docmachine-cli
cd docmachine-cli
make build
make install
```
@ -42,13 +55,14 @@ make install
### Create a New Project
```bash
docmachine scaffold my-doc-project
docmachine scaffold my-documentation-project
```
This command will create a new directory named `my-doc-project` with the following structure:
This command will create a new directory named `my-documentation-project` with
the following structure:
```
my-doc-project
my-documentation-project
├── _build
├── docs
│ └── images # link to ../images
@ -60,7 +74,8 @@ my-doc-project
### Start Writing Content
* **Documentation:** Place your Markdown files inside the `docs` directory.
* **Presentations:** Place your Markdown files (using Marp syntax) inside the `slides` 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
@ -70,6 +85,7 @@ 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`.
@ -100,6 +116,6 @@ We welcome contributions to DocMachine! To contribute:
## License
DocMachine is licensed under the GPL-3.0-or-later license. See the `LICENSE`
file for details.
DocMachine Cli is licensed under the GPL-3.0-or-later license. See the
`LICENSE` file for details.

View file

@ -5,6 +5,7 @@ require "socket"
require "./module"
require "./config"
require "../common/network"
module DocMachine::Build
class Run
@ -19,7 +20,6 @@ module DocMachine::Build
@process = nil
end
# cleanup environment
# create directories
# setup permissions
@ -32,22 +32,6 @@ module DocMachine::Build
self._avoid_duplicates() unless @config.enable_multiple
end
private def _find_port(port_base)
(port_base..65535).each do |port|
return port if _port_available?(port)
end
raise "No port available"
end
private def _port_available?(port)
sock = Socket.new(Socket::Family::INET, Socket::Type::STREAM)
sock.bind(Socket::IPAddress.new("0.0.0.0", port))
sock.close
return true
rescue ex : Socket::BindError
return false
end
private def _avoid_duplicates
Log.info { "Multiple Instances: stopping duplicate containers (for #{@docker_name})" }
docker_cid = %x{docker ps -f "name=#{@docker_name}" -q}.strip
@ -161,7 +145,7 @@ module DocMachine::Build
## Detect docs
if Dir.exists?("#{@config.data_dir}/docs")
Log.info { "Docs: detected docs directory." }
mkdocs_port = _find_port(@config.port)
mkdocs_port = Network.find_port(@config.port)
docker_opt_mkdocs_port = ["-p", "#{mkdocs_port}:5100"]
docker_opts.concat docker_opt_mkdocs_port
Log.notice { "Using port #{mkdocs_port} for docs" }
@ -173,7 +157,7 @@ module DocMachine::Build
## Detect slides
if Dir.exists?("#{@config.data_dir}/slides")
Log.info { "Slides: detected slides directory." }
marp_port = _find_port(@config.port+100)
marp_port = Network.find_port(@config.port+100)
docker_opt_marp_port = ["-p", "#{marp_port}:5200"]
docker_opts.concat docker_opt_marp_port
Log.info { "Slides: Adding option to command line (#{docker_opt_marp_port})" }

19
src/common/network.cr Normal file
View file

@ -0,0 +1,19 @@
class Network
def self.find_port(port_base)
(port_base..65535).each do |port|
return port if self.port_available?(port)
end
raise "No port available"
end
def self.port_available?(port)
sock = Socket.new(Socket::Family::INET, Socket::Type::STREAM)
sock.bind(Socket::IPAddress.new("0.0.0.0", port))
sock.close
return true
rescue ex : Socket::BindError
return false
end
end