Compare commits
3 commits
Author | SHA1 | Date | |
---|---|---|---|
62cdbdb089 | |||
0d4db95186 | |||
6f316ff78e |
3 changed files with 57 additions and 38 deletions
54
README.md
54
README.md
|
@ -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.
|
||||
|
||||
|
|
|
@ -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
19
src/common/network.cr
Normal 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
|
Loading…
Reference in a new issue