dev-libre-is/docs/_source/dev-libre-is.rst

============
dev.libre.is
============
Documentation for this present site.

  `<https://dev.libre.is/>`_

Source code to site:

  `<https://code.libre.is/libre/dev-libre-is>`_



Initial setup
=============

.. 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 dev.libre.is
  sudo mkdir /var/www/html/dev.libre.is
  sudo chown -R jebba:jebba /var/www/html

Apache
======
Apache configuration.

.. code-block:: apache

  <VirtualHost 70.39.110.154:80>
  	ServerName dev.libre.is
  	ServerAdmin webmaster@localhost
  	DocumentRoot /var/www/html/dev-libre-is
  	ErrorLog ${APACHE_LOG_DIR}/error-dev-libre-is.log
  	CustomLog ${APACHE_LOG_DIR}/access-dev-libre-is.log combined
  	RewriteEngine on
  	RewriteCond %{SERVER_NAME} =dev.libre.is
  	RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
  </VirtualHost>
  
  <VirtualHost 70.39.110.154:443>
  	ServerName dev.libre.is
  	ServerAdmin webmaster@localhost
  	DocumentRoot /var/www/html/dev-libre-is
  	ErrorLog ${APACHE_LOG_DIR}/error-dev-libre-is.log
  	CustomLog ${APACHE_LOG_DIR}/access-dev-libre-is.log combined
  	RewriteEngine on
  	ErrorDocument 404 /en/404.html
  	Include /etc/letsencrypt/options-ssl-apache.conf
  	SSLCertificateFile /etc/letsencrypt/live/dev.libre.is/fullchain.pem
  	SSLCertificateKeyFile /etc/letsencrypt/live/dev.libre.is/privkey.pem
  </VirtualHost>
  # vim: syntax=apache ts=4 sw=4 sts=4 sr noet


Docs repo setup
===============
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 dev-libre-is
  cd dev-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 = "dev-libre-is"
  description = "Libre Developer Documentation."
  authors = [
      "Libre Documentation Developers <dev-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://dev.libre.is"
  documentation = "https://dev.libre.is"
  repository = "https://code.libre.is/libre/sndid"
  issues = "https://code.libre.is/libre/sndid/issues"
  changelog = "https://code.libre.is/libre/sndid/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 update
  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
     dev-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/dev-libre-is")
  
  logger = sphinx.util.logging.getLogger(__name__)
  
  project = "dev-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/dev-libre-is
  # or
  git clone git@code.libre.is:libre/dev-libre-is.git
  
  cd dev-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/ dev-libre-is:/var/www/html/dev-libre-is/