Sphinx documentation setup

.gitignore

@@ -1,18 +1,30 @@
 .coverage
+.~lock.*.od?#
 .mypy_cache
 build
+build/
 dist/
 docs/_build/
 htmlcov/
+log
 src/*/_version.py
 tmp
+venv
 *.STEP
 *.brep
 *.brp
 *.db
+*.doctrees
 *.dxf
+*.env
 *.log
+*.mo
 *.msh
+*.pickle
+*.pot
+*.pyc
+*.pyd
+*.pyo
 *.step
 *.stl
 *.stp
@@ -20,4 +32,5 @@ tmp
 *.swp
 *.3mf
 *.egg-info/
+_build/
 __pycache__/

Makefile

@@ -0,0 +1,97 @@
+# Makefile
+# Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf
+
+SPHINXOPTS      ?=
+SPHINXBUILD     ?= sphinx-build
+SOURCEDIR       = docs/_source
+BUILDDIR        = docs/_build
+AUTOBUILDOPTS   = --host 127.0.0.1 --port 8000 --ignore "*.swp" --ignore "*.swx"
+GETTEXT_BUILD   = gettext_build
+UPDATE_LOCALE   = sphinx-intl update -p $(BUILDDIR)/locale/gettext -d $(SOURCEDIR)/locale -l
+PO_FILES        = $(wildcard docs/_source/locale/*/LC_MESSAGES/*.po)
+MSGATTRIB       = msgattrib
+#LANGUAGES       = am ar bg bn ca cak cs cy da de el en eo es et eu fa fi fil fr he hi hr hu id it ja ko lkt lt lv mk mr ms ne nl no pl pt ro ru si sk sl sq sr sv ta te th tr uk ur vi zh
+LANGUAGES       = en
+
+.PHONY: check help html livehtml clean_sphinx clean gettext_build update_locale build_html all copy clean_po latex latexpdf
+
+help:
+	@echo "Please use \`make <target>' where <target> is one of"
+	@echo "  clean                Remove all build files and directories (including translations)"
+	@echo "  all                  Clean and make all targets"
+	@echo "  gettext_build        Build localisation strings for translation"
+	@echo "  update_locale        Update localisation"
+	@echo "  update_locale_<lang> Update localisation for <lang>"
+	@echo "  html                 Build the HTML documentation for all languages"
+	@echo "  html_<lang>          Build HTML documentation for <lang>"
+	@echo "  latex                Build the documentation using LaTeX for all languages"
+	@echo "  latex_<lang>         Build the documentation using LaTeX for <lang>"
+	@echo "  latexpdf             Build the PDFS documentation using LaTeX for all languages"
+	@echo "  latexpdf_<lang>      Build the PDFS documentation using LaTeX for <lang>"
+	@echo "  index                Copy static docs/index.html to docs/_build/html/index.html"
+	@echo "  translations         Translate from English"
+
+all: clean gettext_build update_locale html index
+
+check:
+	@for po in $(PO_FILES); do \
+		echo "Checking $$po..."; \
+		msgfmt --check --output-file=- "$$po" || exit 1; \
+	done
+
+index:
+	cp -p docs/index.html docs/_build/html/index.html
+
+clean:
+	for file in $(PO_FILES); do \
+	    $(MSGATTRIB) --no-obsolete -o $$file $$file; \
+	done
+	cd docs && make clean
+	find $(SOURCEDIR) -type f -name "*.mo" -delete
+	rm -rf $(BUILDDIR)/*
+
+gettext_build:
+	$(SPHINXBUILD) -b gettext -c $(SOURCEDIR) -d $(BUILDDIR)/doctrees/$(GETTEXT_BUILD) $(SOURCEDIR) $(BUILDDIR)/locale/gettext
+
+update_locale:
+	@pids="" ; \
+	for lang in $(LANGUAGES); do \
+	    ( echo "Updating locale for $$lang..." ; $(UPDATE_LOCALE) $$lang ) & pids="$$pids $$!" ; \
+	done ; \
+	for pid in $$pids; do \
+	    wait $$pid ; \
+	done
+
+update_locale_%:
+	$(UPDATE_LOCALE) $*
+
+html:
+	@for lang in $(LANGUAGES); do \
+	    echo "Building HTML documentation for $$lang..."; \
+	    $(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees -D language=$$lang $(SOURCEDIR) $(BUILDDIR)/html/$$lang; \
+	done
+
+html_%: gettext_build
+	$(SPHINXBUILD) -b html -d $(BUILDDIR)/doctrees -D language=$* -c $(SOURCEDIR) $(SOURCEDIR) $(BUILDDIR)/html/$*/
+
+latex:
+	@for lang in $(LANGUAGES); do \
+		echo "Building LaTeX documentation for $$lang..."; \
+		$(SPHINXBUILD) -b latex -d $(BUILDDIR)/doctrees -D language=$$lang -Dlatex_engine=xelatex $(SOURCEDIR) $(BUILDDIR)/latex/$$lang; \
+	done
+
+latex_%:
+	$(SPHINXBUILD) -b latex -d $(BUILDDIR)/doctrees -D language=$* -Dlatex_engine=xelatex $(SOURCEDIR) $(BUILDDIR)/latex/$*/; \
+
+latexpdf:
+	@for lang in $(filter-out ar he ja,$(LANGUAGES)); do \
+		echo "Building PDF documentation for $$lang..."; \
+		$(MAKE) -C $(BUILDDIR)/latex/$$lang ; \
+	done
+
+latexpdf_%:
+	$(MAKE) -C $(BUILDDIR)/latex/$* ; \
+
+translations:
+	./scripts/translate-all.sh
+

README.md

@@ -4,6 +4,22 @@ Wet Rocks, a single phase immersion cooled computer.
 * https://wetrocks.fyi
 
 
+# Build
+Build thusly.
+Adjust Python setup to suit to taste.
+
+```
+git clone --recursive https://spacecruft.org/deepcrayon/wetrocks
+cd wetrocks/
+virtualenv venv
+source venv/bin/activate
+pip install -U setuptools pip wheel
+pip install -r requirements.txt
+pip install -e .
+make all
+```
+
+
 # License
 Apache 2.0 license.
 

docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = _source
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/_source/_static/custom.css

@@ -0,0 +1,8 @@
+
+/* Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf */
+div.footer-wrapper {
+    display: none;
+}
+.wy-nav-content {
+   max-width: 95%;
+}

docs/_source/about.rst

@@ -0,0 +1,32 @@
+=====
+About
+=====
+Wet Rocks, a single phase immersion cooled computer.
+
+
+Status
+======
+
+* Draft.
+
+
+Links
+=====
+
+  `<https://wetrocks.fyi/>`_
+
+  `<https://spacecruft.org/deepcrayon/wetrocks>`_
+
+
+Licenses
+========
+This documentation is provided under the Apache 2.0 license.
+
+Copyright 2024, Jeff Moe
+
+
+Author
+======
+| Jeff Moe <moe@parrot.codes>
+| Loveland, Colorado, USA
+

docs/_source/conf.py

@@ -0,0 +1,72 @@
+import sys, os
+import sphinx.util.logging
+
+logger = sphinx.util.logging.getLogger(__name__)
+
+project = "Wet Rocks"
+copyright = "2024, Jeff Moe"
+author = "Jeff Moe"
+version = "0"
+release = "0.0.0"
+extensions = [
+    "notfound.extension",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+    "sphinxcontrib.exceltable",
+]
+templates_path = ["_templates"]
+exclude_patterns = []
+source_suffix = ".rst"
+master_doc = "index"
+pygments_style = "staroffice"
+python_display_short_literal_types = True
+todo_include_todos = False
+html_show_copyright = False
+html_static_path = ["_static"]
+html_favicon = '_static/favicon.ico'
+html_logo = '_static/logo.png'
+html_last_updated_fmt: None
+html_show_sphinx = False
+html_show_sourcelink = False
+html_link_suffix = ".html"
+html_theme = "sphinx_rtd_theme"
+html_theme_options = {
+    "style_nav_header_background": "#4fb31f",
+    "display_version": False,
+    "prev_next_buttons_location": "bottom",
+    "collapse_navigation": True,
+    "sticky_navigation": True,
+    "navigation_depth": 4,
+    "includehidden": True,
+    "titles_only": False,
+}
+
+html_css_files = [
+    "custom.css",
+]
+html_context = {
+    "display_lower_left": True,
+}
+
+locale_dirs = ["locale/"]
+gettext_compact = False
+language = "en"
+# languages = ('am', 'ar', 'bn', 'de', 'el', 'en', 'eo', 'es', 'eu', 'fil', 'fr', 'he', 'hi', 'id', 'it', 'ja', 'ko', 'mr', 'ms', 'nl', 'pl', 'pt', 'ru', 'see', 'ta', 'te', 'th', 'tr', 'ur', 'vi', 'zh')
+languages = ('en')
+html_search_language = "en"
+
+latex_engine = "xelatex"
+latex_elements = {
+    "extraclassoptions": "openany,oneside",
+    "sphinxsetup": "hmargin={1in,1in}, vmargin={1in,1in}",
+    "inputenc": "",
+    "utf8extra": "",
+    "preamble": r"""
+\usepackage{xcolor}
+\usepackage{polyglossia}
+    """,
+}
+
+notfound_urls_prefix = "/en/"

docs/_source/index.rst

@@ -0,0 +1,14 @@
+=========
+Wet Rocks
+=========
+Wet Rocks, a single phase immersion cooled computer.
+
+Alpha, under development.
+
+
+.. toctree::
+   about
+   source
+   :maxdepth: 2
+   :caption: Contents:
+

docs/_source/source.rst

@@ -0,0 +1,8 @@
+===========
+Source Code
+===========
+
+Wet Rocks source code repository:
+
+  `<https://spacecruft.org/deepcrayon/wetrocks>`_
+

docs/index.html

@@ -0,0 +1,28 @@
+<!DOCTYPE html>
+<html lang="en">
+<!-- Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf -->
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>milkV Pioneer</title>
+    <noscript>
+        <meta http-equiv="refresh" content="1; url=/en/" />
+    </noscript>
+    <script>
+        document.addEventListener('DOMContentLoaded', function() {
+            var language = navigator.language || navigator.userLanguage;
+            var path = '/en/';
+
+            switch (language.substr(0, 2)) {
+                case 'en':
+                    path = '/en/';
+                    break;
+            }
+
+            window.location.href = path;
+        });
+    </script>
+</head>
+<body>
+</body>
+</html>

requirements.txt

@@ -0,0 +1,11 @@
+polib
+pycountry
+requests
+sphinx
+sphinxcontrib-exceltable
+sphinxcontrib-markdown
+sphinx-autobuild
+sphinx-autodoc-typehints
+sphinx-intl
+sphinx-notfound-page
+sphinx-rtd-theme

scripts/rsync-docs

@@ -0,0 +1,36 @@
+#!/bin/bash
+# This script pushes the html files to the main server.
+# Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf
+
+# Functions declaration
+function check_file() {
+    if [ ! -f "$1" ]; then
+        echo "The $1 file does not exist."
+        exit 1
+    else
+        source "$1"
+    fi
+}
+
+function push_files() {
+    rsync \
+        -ultav \
+        "$1" \
+        "${URL}"
+
+    rsync \
+        -ultav \
+        --delete-after \
+        "$1" \
+        "${URL}"
+}
+
+# Main script execution
+check_file ".env"
+
+if [ -z "${URL}" ]; then
+    echo "Please add the URL to .env using the format: URL=\"<server_url>\""
+    exit 1
+fi
+
+push_files "./docs/_build/html/"

scripts/rsync-docs-local

@@ -0,0 +1,20 @@
+#!/bin/bash
+# This script pushes the html files to the main server.
+# Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf
+
+URL=/var/www/html/
+
+function push_files() {
+    rsync \
+        -ultav \
+        "$1" \
+        "${URL}"
+
+    rsync \
+        -ultav \
+        --delete-after \
+        "$1" \
+        "${URL}"
+}
+
+push_files "./docs/_build/html/"

scripts/translate-all.sh

@@ -0,0 +1,15 @@
+#!/bin/bash
+
+SOURCEDIR="./docs/_source/locale/"
+PYSCRIPT="`pwd`/scripts/translate.py"
+
+cd ${SOURCEDIR}
+# for LANGTR in am ar bn de el eo es eu fil fr he hi id it ja ko lkt mr ms nl pl pt ru see ta te th tr ur vi zh
+for LANGTR in zh
+    do echo "Translating language ${LANGTR}..."
+        for PO in `find ${LANGTR}/LC_MESSAGES/ -name "*.po"`
+            do echo "Translating file: ${PO}"
+                ${PYSCRIPT} --lang ${LANGTR} --file ${PO}
+        done
+done
+

scripts/translate.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python3
+# Jeff Moe with Parrot and Phind-CodeLlama-34B-v2_q8.gguf
+
+import requests
+import json
+from gettext import gettext as _
+import polib
+import re
+import argparse
+from pycountry import languages
+
+# Set to llama server IP and port.
+API = "http://192.168.109.223:8080/completion"
+
+
+def update_po_file(filename, msgid, new_translation):
+    po = polib.pofile(filename)
+
+    for entry in po:
+        if entry.msgid == msgid:
+            entry.msgstr = new_translation
+            break
+
+    po.save()
+
+
+def process_response(json_data):
+    formatted_content = json_data["content"].replace("\\n", "\n").replace("\\u", "\\")
+    formatted_content = formatted_content.replace("```", "")
+    lines = formatted_content.split("\n")
+
+    formatted_msgid, formatted_msgstr = None, None
+
+    for line in lines:
+        if line.startswith("msgid"):
+            formatted_msgid = line.replace("msgid: ", "")
+        elif line.startswith("msgstr"):
+            formatted_msgstr = line.replace("msgstr: ", "")
+
+    return formatted_msgid, formatted_msgstr
+
+
+def get_lang_name(iso_code):
+    try:
+        if len(iso_code) == 2:
+            lang = languages.get(alpha_2=iso_code)
+        elif len(iso_code) == 3:
+            lang = languages.get(alpha_3=iso_code)
+        else:
+            raise KeyError
+        return lang.name
+    except (KeyError, TypeError):
+        print(f"Unknown language code: {iso_code}")
+        return None
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("--file", help=".po file", required=True)
+    parser.add_argument(
+        "--lang", help='Language ISO 639 code (e.g. "en")', required=True
+    )
+    args = parser.parse_args()
+
+    POFILE = args.file
+    DESTISO = args.lang
+    DESTLANG = get_lang_name(DESTISO)
+
+    if not POFILE:
+        print("Please provide a POFILE using --file option")
+        return
+
+    pofile = polib.pofile(POFILE)
+
+    for entry in pofile:
+        poprompt = f"msgid: {entry.msgid}\nmsgstr: {entry.msgstr}\n"
+
+        PROMPT = _("translate into " + DESTLANG + "(" + DESTISO + ")")
+
+        PROMPT = _(
+            """### System Prompt
+        You are an expert translator and programmer and write code on the first attempt without any errors or fillers.
+        ### User Message:
+        Rewrite the code to satisfy this request: "This is a gettext .po file.
+        The English "msgid" needs to be translated into 
+        """
+            + DESTLANG
+            + "("
+            + DESTISO
+            + ")"
+            """
+        The translated string goes into "msgstr". Keep the English "msgid", dont change the English.
+        Professional translation. Do not change any instructions. ONLY TRANSLATE text.
+        DO NOT TRANSLATE URLs between "<" and ">" symbols.
+        DO NOT change the "msgid".
+        DO NOT translate the following proper names in the "msgstr": "Parrot".
+        ONLY write "Here is the translated code:" and display the code.
+        """
+            + "```"
+            + poprompt
+            + "```"
+        )
+
+        headers = {"Content-Type": "application/json"}
+        data = {"prompt": PROMPT, "n_predict": 128}
+        response = requests.post(API, headers=headers, json=data)
+        json_data = response.json()
+
+        formatted_msgid, formatted_msgstr = process_response(json_data)
+
+        print(f"msgid: {formatted_msgid}")
+        print(f"msgstr: {formatted_msgstr}")
+
+        update_po_file(POFILE, formatted_msgid, formatted_msgstr)
+
+
+if __name__ == "__main__":
+    main()