From 4cec9992845603e60976f545241766f24519ddc4 Mon Sep 17 00:00:00 2001 From: Jeff Moe Date: Sat, 31 Aug 2024 15:15:09 -0600 Subject: [PATCH] sphinx dev-libre-is draft docs --- docs/_source/dev-libre-is.rst | 496 ++++++++++++++++++ .../locale/en/LC_MESSAGES/dev-libre-is.po | 87 ++- 2 files changed, 579 insertions(+), 4 deletions(-) diff --git a/docs/_source/dev-libre-is.rst b/docs/_source/dev-libre-is.rst index d7af61d..f8eee98 100644 --- a/docs/_source/dev-libre-is.rst +++ b/docs/_source/dev-libre-is.rst @@ -10,6 +10,502 @@ Source code to site: ``_ + +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 + + + 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] + + + + 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 + + # 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 " + ] + 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 ' where 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_ Update localisation for " + @echo " html Build the HTML documentation for all languages" + @echo " html_ Build HTML documentation for " + @echo " latex Build the documentation using LaTeX for all languages" + @echo " latex_ Build the documentation using LaTeX for " + @echo " latexpdf Build the PDFS documentation using LaTeX for all languages" + @echo " latexpdf_ Build the PDFS documentation using LaTeX for " + @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 + + + + + + + muh project. + + + + + + + + +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 %} + + + {% 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. diff --git a/docs/_source/locale/en/LC_MESSAGES/dev-libre-is.po b/docs/_source/locale/en/LC_MESSAGES/dev-libre-is.po index 938a178..8c72b84 100644 --- a/docs/_source/locale/en/LC_MESSAGES/dev-libre-is.po +++ b/docs/_source/locale/en/LC_MESSAGES/dev-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 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 \n" "Language: en\n" @@ -40,11 +40,90 @@ msgstr "" msgid "``_" 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 "" -