From 46929337801568c8ae90bb182b17329c95cedbb1 Mon Sep 17 00:00:00 2001
From: Jeff Moe <moe@libre.is>
Date: Mon, 2 Sep 2024 05:54:12 -0600
Subject: [PATCH] docs-libre-is page based on dev-libre-is

---
 docs/_source/docs-libre-is.rst                | 534 ++++++++++++++++++
 .../locale/en/LC_MESSAGES/docs-libre-is.po    | 120 +++-
 2 files changed, 653 insertions(+), 1 deletion(-)

diff --git a/docs/_source/docs-libre-is.rst b/docs/_source/docs-libre-is.rst
index b7c6689..a6f00cb 100644
--- a/docs/_source/docs-libre-is.rst
+++ b/docs/_source/docs-libre-is.rst
@@ -5,3 +5,537 @@ Documentation for Libre user documentation server.
 
   `<https://docs.libre.is>`_
 
+Source code to docs site:
+
+  `<https://code.libre.is/libre/docs-libre-is>`_
+
+
+Apache
+======
+
+.. code-block:: sh
+
+  sudo apt install python3-certbot-apache gettext make
+  # If LaTeX builds are to be used:
+  sudo apt install texlive-full
+  sudo certbot -d docs.libre.is
+  sudo mkdir /var/www/html/docs.libre.is
+  sudo chown -R jebba:jebba /var/www/html
+
+
+Apache configuration /etc/apache2/sites-enabled/docs-libre-is.conf
+
+.. code-block:: apache
+
+  <VirtualHost 70.39.110.153:80>
+  	ServerName docs.libre.is
+  	ServerAdmin webmaster@localhost
+  	DocumentRoot /var/www/html/docs-libre-is
+  	ErrorLog ${APACHE_LOG_DIR}/error-docs-libre-is.log
+  	CustomLog ${APACHE_LOG_DIR}/access-docs-libre-is.log combined
+  	RewriteEngine on
+  	RewriteCond %{SERVER_NAME} =docs.libre.is
+  	RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
+  </VirtualHost>
+  
+  <VirtualHost 70.39.110.153:443>
+  	ServerName docs.libre.is
+  	ServerAdmin webmaster@localhost
+  	DocumentRoot /var/www/html/docs-libre-is
+  	ErrorLog ${APACHE_LOG_DIR}/error-docs-libre-is.log
+  	CustomLog ${APACHE_LOG_DIR}/access-docs-libre-is.log combined
+  	RewriteEngine on
+  	ErrorDocument 404 /en/404.html
+  	Include /etc/letsencrypt/options-ssl-apache.conf
+  	SSLCertificateFile /etc/letsencrypt/live/docs.libre.is/fullchain.pem
+  	SSLCertificateKeyFile /etc/letsencrypt/live/docs.libre.is/privkey.pem
+  </VirtualHost>
+  # vim: syntax=apache ts=4 sw=4 sts=4 sr noet
+
+
+Docs repo setup
+===============
+Create a source code git repo on Libre code.
+
+Initial setup like below.
+
+At the bottom is a mini-HOWTO to build the site now that the repo already
+exists.
+
+.. code-block:: sh
+
+  mkdir docs-libre-is
+  cd docs-libre-is/
+  mkdir -p docs/_source/locale docs/_build docs/_source/_templates
+  mkdir -p docs/_source/_static/
+  python -m venv venv
+  source venv/bin/activate
+  pip install -U pip wheel poetry
+
+Create poetry file `pyproject.toml`:
+
+.. code-block:: toml
+
+  # pyproject.toml
+  
+  [tool.poetry]
+  name = "docs-libre-is"
+  description = "Libre Developer Documentation."
+  authors = [
+      "Libre Documentation Developers <docs-libre-is@libre.is>"
+  ]
+  license = "Apache-2.0"
+  # https://pypi.org/classifiers/
+  classifiers = [
+      "Development Status :: 3 - Alpha",
+      "Environment :: Console",
+      "Intended Audience :: Developers",
+      "Intended Audience :: Education",
+      "License :: OSI Approved :: Apache Software License",
+      "Natural Language :: English",
+      "Operating System :: POSIX :: Linux",
+      "Programming Language :: Python :: 3",
+      "Topic :: Education",
+  ]
+  
+  readme = "README.md"
+  version = "0.0.1"
+  
+  # If a Python code subdirectory is used:
+  # packages = [
+  #    { include = "foocode" },
+  # ]
+  package-mode = false
+  
+  [tool.poetry.dependencies]
+  polib = "*"
+  pycountry = "*"
+  pygments = "*"
+  python = ">=3.10"
+  requests = "*"
+  setuptools_scm = "*"
+  sphinx = "*"
+  sphinx-autobuild = "*"
+  sphinx-autodoc-typehints = "*"
+  sphinx-intl = "*"
+  sphinx-notfound-page = "*"
+  sphinx-rtd-theme = "*"
+  sphinxcontrib-markdown = "*"
+  
+  [build-system]
+  requires = ["poetry-core", "setuptools_scm"]
+  build-backend = "poetry.core.masonry.api"
+  
+  # If separate scripts are do be added
+  # [tool.poetry.scripts]
+  # librescript   = "librescript:main"
+  
+  
+  [tool.poetry.urls]
+  homepage = "https://docs.libre.is"
+  documentation = "https://docs.libre.is"
+  repository = "https://code.libre.is/libre/docs-libre-is"
+  issues = "https://code.libre.is/libre/docs-libre-is/issues"
+  changelog = "https://code.libre.is/libre/docs-libre-is/raw/branch/main/CHANGELOG.txt"
+  
+  # Directory of Python scripts, if used.
+  # [options.packages.find]
+  # include = "libre"
+  # [options.package_data]
+  # libre = "_version.py"
+  
+  [tool.poetry.dev-dependencies]
+  black = "*"
+  poetry = "*"
+  pyprof2calltree = "*"
+  # Linter
+  # ruff = "*"
+  # If pushed to pypi
+  # twine = "*"
+  
+  # Auto versioning for scripts
+  # [tool.setuptools_scm]
+  # write_to = "libre/_version.py"
+  
+  # If linter is used
+  # [tool.ruff]
+  # line-length = 88
+  # [tool.ruff.lint]
+  # select = [
+  #    "E",
+  #    "W",
+  #    "F",
+  #]
+  # ignore = [ "E501" ]
+
+
+.. code-block:: sh
+
+  touch README.md CHANGELOG.txt
+  poetry install
+
+Perhaps a `.gitignore` like:
+
+.. code-block:: cfg
+
+  log
+  tmp
+  venv
+  *.doctrees
+  *.env
+  *.mo
+  *.pickle
+  *.pot
+  *.pyc
+  *.pyd
+  *.swp
+  *.pyo 
+  _build/
+  __pycache__/
+
+
+Makefile
+========
+
+.. code-block:: makefile
+
+  # Makefile
+  
+  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
+
+Copy over an appropriate license file to the repo, such as `LICENSE-apache.txt`.
+
+
+docs/index.html
+===============
+
+.. code-block:: html
+
+  <!DOCTYPE html>
+  <html lang="en">
+  <head>
+      <meta charset="UTF-8">
+      <meta name="viewport" content="width=device-width, initial-scale=1.0">
+      <title>muh project.</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>
+
+
+docs/Makefile
+=============
+
+.. code-block:: makefile
+
+  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/index.rst
+======================
+Example file.
+
+.. code-block:: RST
+
+  ==============================
+  Libre Developers Documentation
+  ==============================
+  
+  Libre developers documentation.
+  
+  * All the things
+  
+      
+  .. toctree::
+     about
+     libre-is
+     code-libre-is
+     docs-libre-is
+     docs-libre-is
+     forms-libre-is
+     mail-libre-is
+     license
+     :maxdepth: 2
+     :caption: Contents:
+
+
+Create other `docs/_source/about.rst` or other appropriate files.
+
+
+docs/_source/conf.py
+====================
+
+.. code-block:: python
+
+  import sys, os
+  import sphinx.util.logging
+  
+  sys.path.append("../../src/docs-libre-is")
+  
+  logger = sphinx.util.logging.getLogger(__name__)
+  
+  project = "docs-libre-is: very project"
+  copyright = "2024, Muh Author Name"
+  author = "Muh Author Name"
+  version = "0"
+  release = "0.4.3"
+  extensions = [
+      "notfound.extension",
+      "sphinx.ext.autodoc",
+      "sphinx.ext.intersphinx",
+      "sphinx.ext.napoleon",
+      "sphinx.ext.viewcode",
+  ]
+  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/"
+
+Set up templates
+================
+
+File `docs/_source/_templates/layout.html`
+
+.. code-block:: html
+
+  {% extends "!layout.html" %}
+  
+  {%- block extrahead %} 
+  <link rel="stylesheet" type="text/css" href="{{ pathto('_static/handsontable.full.min.css', 1) }}">
+  <script src="{{ pathto('_static/handsontable.full.min.js', 1) }}"></script>
+  {% endblock %}
+  
+
+If LaTex is to be used, `docs/_source/_templates/latex.tex`
+  
+.. code-block:: latex
+
+  {% extends 'article.tpl' %}
+  
+  {% block packages %}
+  \usepackage{fontspec}
+  {{ super() }}
+  {% endblock packages %}
+
+
+Set up `docs/_source/_static/custom.css`
+========================================
+
+.. code-block:: css
+
+  div.footer-wrapper {
+      display: none;
+  }
+  .wy-nav-content {
+     max-width: 95%;
+  }
+
+
+Images
+======
+
+Add a `favicon.ico` and `logo.png` to `docs/_source/_static/`
+
+If spreadsheet is going to be used/imported, add to here `docs/_source/_static/` these files:
+
+`handsontable.full.min.css` and `handsontable.full.min.js`
+
+
+.. code-block:: sh
+
+  cd docs/_source/_static/
+  
+  wget https://raw.githubusercontent.com/handsontable/handsontable/develop/handsontable/dist/handsontable.full.min.css
+  
+  wget https://raw.githubusercontent.com/handsontable/handsontable/develop/handsontable/dist/handsontable.full.min.js
+  cd ../../..
+
+
+Build
+=====
+HOWTO build this site.
+
+.. code-block:: sh
+
+  git clone https://code.libre.is/libre/docs-libre-is
+  # or
+  git clone git@code.libre.is:libre/docs-libre-is.git
+  
+  cd docs-libre-is/
+  python -m venv venv
+  source venv/bin/activate
+  pip install -U pip poetry
+  poetry install
+  make clean
+  make all
+  rsync -ultav docs/_build/html/ docs-libre-is:/var/www/html/docs-libre-is/
+
diff --git a/docs/_source/locale/en/LC_MESSAGES/docs-libre-is.po b/docs/_source/locale/en/LC_MESSAGES/docs-libre-is.po
index bfd7eed..e8361ef 100644
--- a/docs/_source/locale/en/LC_MESSAGES/docs-libre-is.po
+++ b/docs/_source/locale/en/LC_MESSAGES/docs-libre-is.po
@@ -9,7 +9,7 @@ msgid ""
 msgstr ""
 "Project-Id-Version: Libre Developers Documentation 0\n"
 "Report-Msgid-Bugs-To: \n"
-"POT-Creation-Date: 2024-08-31 14:57-0600\n"
+"POT-Creation-Date: 2024-09-02 05:52-0600\n"
 "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
 "Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
 "Language: en\n"
@@ -31,3 +31,121 @@ msgstr ""
 #: ../../../_source/docs-libre-is.rst:6
 msgid "`<https://docs.libre.is>`_"
 msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:8
+msgid "Source code to docs site:"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:10
+msgid "`<https://code.libre.is/libre/docs-libre-is>`_"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:14
+msgid "Apache"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:26
+msgid "Apache configuration /etc/apache2/sites-enabled/docs-libre-is.conf"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:57
+msgid "Docs repo setup"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:58
+msgid "Create a source code git repo on Libre code."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:60
+msgid "Initial setup like below."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:62
+msgid ""
+"At the bottom is a mini-HOWTO to build the site now that the repo already "
+"exists."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:75
+msgid "Create poetry file `pyproject.toml`:"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:177
+msgid "Perhaps a `.gitignore` like:"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:198
+msgid "Makefile"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:298
+msgid ""
+"Copy over an appropriate license file to the repo, such as `LICENSE-apache."
+"txt`."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:302
+msgid "docs/index.html"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:335
+msgid "docs/Makefile"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:354
+msgid "docs/_source/index.rst"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:355
+msgid "Example file."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:381
+msgid "Create other `docs/_source/about.rst` or other appropriate files."
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:385
+msgid "docs/_source/conf.py"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:464
+msgid "Set up templates"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:466
+msgid "File `docs/_source/_templates/layout.html`"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:478
+msgid "If LaTex is to be used, `docs/_source/_templates/latex.tex`"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:491
+msgid "Set up `docs/_source/_static/custom.css`"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:504
+msgid "Images"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:506
+msgid "Add a `favicon.ico` and `logo.png` to `docs/_source/_static/`"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:508
+msgid ""
+"If spreadsheet is going to be used/imported, add to here `docs/_source/"
+"_static/` these files:"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:510
+msgid "`handsontable.full.min.css` and `handsontable.full.min.js`"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:524
+msgid "Build"
+msgstr ""
+
+#: ../../../_source/docs-libre-is.rst:525
+msgid "HOWTO build this site."
+msgstr ""