docs: add missing information to README

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.
 

src/build/run.cr

@@ -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})" }

src/common/network.cr

@@ -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