sphinx dev-libre-is draft docs

This commit is contained in:
Jeff Moe 2024-08-31 15:15:09 -06:00
parent f6558f77e6
commit 4cec999284
2 changed files with 579 additions and 4 deletions

View file

@ -10,6 +10,502 @@ 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 muh-domain.foobar
sudo mkdir /var/www/html/muh-domain.foobar
sudo chown -R muhuser:muhuser /var/www/html
Apache
======
.. code-block:: sh
<VirtualHost 192.168.1.1:80>
ServerName muh-domain.foobar
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html/muh-domain.foobar
ErrorLog ${APACHE_LOG_DIR}/error-muh-domain.foobar.log
CustomLog ${APACHE_LOG_DIR}/access-muh-domain.foobar.log combined
RewriteEngine on
RewriteCond %{SERVER_NAME} =muh-domain.foobar
RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,NE,R=permanent]
</VirtualHost>
<VirtualHost 192.168.1.1:443>
ServerName muh-domain.foobar
ServerAdmin webmaster@localhost
DocumentRoot /var/www/html/muh-domain.foobar
ErrorLog ${APACHE_LOG_DIR}/error-muh-domain.foobar.log
CustomLog ${APACHE_LOG_DIR}/access-muh-domain.foobar.log combined
RewriteEngine on
ErrorDocument 404 /en/404.html
Include /etc/letsencrypt/options-ssl-apache.conf
SSLCertificateFile /etc/letsencrypt/live/muh-domain.foobar/fullchain.pem
SSLCertificateKeyFile /etc/letsencrypt/live/muh-domain.foobar/privkey.pem
</VirtualHost>
# vim: syntax=apache ts=4 sw=4 sts=4 sr noet
Docs repo setup
===============
.. code-block:: sh
mkdir muhproject
cd muhproject/
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:: sh
# 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" },
# ]
[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 install
Perhaps a `.gitignore` like:
.. code-block:: sh
log
tmp
venv
*.doctrees
*.env
*.mo
*.pickle
*.pot
*.pyc
*.pyd
*.swp
*.pyo
_build/
__pycache__/
Makefile, etc.
.. code-block:: sh
# 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`.
Set up `docs/index.html`
========================
.. code-block:: sh
<!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>
Set up docs/Makefile
====================
.. code-block:: sh
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)
Create `docs/_source/index.rst`
===============================
.. code-block:: sh
==========
muhproject
==========
muhproject is an fooooooo.
* All the things
.. toctree::
about
source
license
:maxdepth: 2
:caption: Contents:
Create other `docs/_source/about.rst` or aother appropriate files.
Set up `docs/_source/conf.py`
=============================
.. code-block:: sh
import sys, os
import sphinx.util.logging
sys.path.append("../../src/muhproject")
logger = sphinx.util.logging.getLogger(__name__)
project = "muhproject: 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:: sh
{% 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:: sh
{% extends 'article.tpl' %}
{% block packages %}
\usepackage{fontspec}
{{ super() }}
{% endblock packages %}
Set up `docs/_source/_static/custom.css`
========================================
.. code-block:: sh
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.

View file

@ -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 15:05-0600\n"
"POT-Creation-Date: 2024-08-31 15:13-0600\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: en\n"
@ -40,11 +40,90 @@ msgstr ""
msgid "`<https://code.libre.is/libre/dev-libre-is>`_"
msgstr ""
#: ../../../_source/dev-libre-is.rst:14
#: ../../../_source/dev-libre-is.rst:15
msgid "Initial setup"
msgstr ""
#: ../../../_source/dev-libre-is.rst:27
msgid "Apache"
msgstr ""
#: ../../../_source/dev-libre-is.rst:59
msgid "Docs repo setup"
msgstr ""
#: ../../../_source/dev-libre-is.rst:71
msgid "Create poetry file `pyproject.toml`:"
msgstr ""
#: ../../../_source/dev-libre-is.rst:172
msgid "Perhaps a `.gitignore` like:"
msgstr ""
#: ../../../_source/dev-libre-is.rst:191
msgid "Makefile, etc."
msgstr ""
#: ../../../_source/dev-libre-is.rst:291
msgid ""
"Copy over an appropriate license file to the repo, such as `LICENSE-apache."
"txt`."
msgstr ""
#: ../../../_source/dev-libre-is.rst:295
msgid "Set up `docs/index.html`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:328
msgid "Set up docs/Makefile"
msgstr ""
#: ../../../_source/dev-libre-is.rst:347
msgid "Create `docs/_source/index.rst`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:366
msgid "Create other `docs/_source/about.rst` or aother appropriate files."
msgstr ""
#: ../../../_source/dev-libre-is.rst:369
msgid "Set up `docs/_source/conf.py`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:447
msgid "Set up templates"
msgstr ""
#: ../../../_source/dev-libre-is.rst:449
msgid "File `docs/_source/_templates/layout.html`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:474
msgid "Set up `docs/_source/_static/custom.css`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:487
msgid "Images"
msgstr ""
#: ../../../_source/dev-libre-is.rst:489
msgid "Add a `favicon.ico` and `logo.png` to `docs/_source/_static/`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:491
msgid ""
"If spreadsheet is going to be used/imported, add to here `docs/_source/"
"_static/` these files:"
msgstr ""
#: ../../../_source/dev-libre-is.rst:493
msgid "`handsontable.full.min.css` and `handsontable.full.min.js`"
msgstr ""
#: ../../../_source/dev-libre-is.rst:507
msgid "Build"
msgstr ""
#: ../../../_source/dev-libre-is.rst:15
#: ../../../_source/dev-libre-is.rst:508
msgid "HOWTO build this site."
msgstr ""