aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorWojtek Kosior <koszko@koszko.org>2022-10-28 20:15:30 +0200
committerWojtek Kosior <koszko@koszko.org>2022-10-28 20:15:30 +0200
commit43ed7392cdfc734a4304284906b9d0d503381841 (patch)
tree5d78662357507aac0820825a8ace0859c395779d
parent2a622842c38f1f9df2aee6af28bf9932d05a2ef0 (diff)
downloadhaketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.tar.gz
haketilo-hydrilla-43ed7392cdfc734a4304284906b9d0d503381841.zip
[proxy] make it possible to export embedded documentation as standalone .html files and include these in the binary release tarball
-rw-r--r--.gitignore1
-rw-r--r--Makefile13
-rwxr-xr-xsetup.py57
-rw-r--r--src/hydrilla/proxy/self_doc.py8
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/advanced_ui_features.html.jinja (renamed from src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/doc_index.html.jinja (renamed from src/hydrilla/proxy/self_doc/doc_index.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/packages.html.jinja (renamed from src/hydrilla/proxy/self_doc/packages.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja (renamed from src/hydrilla/proxy/self_doc/policy_selection.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/popup.html.jinja (renamed from src/hydrilla/proxy/self_doc/popup.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/repositories.html.jinja (renamed from src/hydrilla/proxy/self_doc/repositories.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja (renamed from src/hydrilla/proxy/self_doc/script_blocking.html.jinja)0
-rw-r--r--src/hydrilla/proxy/self_doc/en_US/url_patterns.html.jinja (renamed from src/hydrilla/proxy/self_doc/url_patterns.html.jinja)0
-rw-r--r--src/hydrilla/proxy/web_ui/root.py8
-rw-r--r--src/hydrilla/translations.py8
14 files changed, 79 insertions, 16 deletions
diff --git a/.gitignore b/.gitignore
index f24719d..d758574 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,3 +15,4 @@ messages.mo
make-release.log
*-tarball-repack
haketilo-and-hydrilla-bin-*.tar.gz
+htmldoc/
diff --git a/Makefile b/Makefile
index 1cfdd82..f98362e 100644
--- a/Makefile
+++ b/Makefile
@@ -50,10 +50,13 @@ dist src/hydrilla/_version.py:
@printf "Generated source tarball in:\n"
@printf "./dist/hydrilla-$(GET_VER).tar.gz\n"
+doc:
+ $(GUIX_DEVSHELL) python3 setup.py build_htmldoc
+
# Make a release tarball and repack its files as writeable - this will make it
# easier for non-technical users to remove the unpacked release once they no
# longer need it.
-release: dist
+release: dist doc
$(GUIX_TM) pack -L ./hydrilla-guix -RR hydrilla \
-S /hydrilla=bin/hydrilla \
-S /hydrilla-builder=bin/hydrilla-builder \
@@ -67,6 +70,7 @@ release: dist
mkdir bin-tarball-repack/"$$RELNAME" && \
tar -C bin-tarball-repack/"$$RELNAME"/ -xf "$$PACKFILE" && \
chmod -R +w bin-tarball-repack/"$$RELNAME" && \
+ cp -R htmldoc/ bin-tarball-repack/"$$RELNAME" && \
$(DETERMINISTIC_TAR) -C bin-tarball-repack/ \
-cf "$$RELNAME".tar.gz "$$RELNAME"
@printf "Generated binary release tarball for $$(arch) in:\n"
@@ -132,7 +136,10 @@ clean-bin-tarball-repack:
clean-source-tarball-repack:
rm -rf source-tarball-repack/
-clean: clean-bin-tarball-repack clean-source-tarball-repack
+clean-doc:
+ rm -rf htmldoc/
+
+clean: clean-bin-tarball-repack clean-source-tarball-repack clean-doc
rm -rf build/ dist/ src/hydrilla.egg-info/ src/hydrilla/_version.py \
src/hydrilla/locales/messages.pot make-release.log \
haketilo-and-hydrilla-bin-*.tar.gz .mypy_cache/ .pytest_cache/
@@ -140,7 +147,7 @@ clean: clean-bin-tarball-repack clean-source-tarball-repack
rm -rf $$(find -name "__pycache__")
.PHONY: shell shell-with-haketilo \
- release dist wheel catalogs \
+ wheel dist doc release catalogs \
refresh-catalogs test run-haketilo \
mypy-lint mypy-lint-server mypy-lint-builder mypy-lint-haketilo \
clean-bin-tarball-repack clean-source-tarball-repack clean
diff --git a/setup.py b/setup.py
index 3aa9f74..a8a5bfa 100755
--- a/setup.py
+++ b/setup.py
@@ -9,6 +9,7 @@ import setuptools
from setuptools.command.build_py import build_py
from setuptools.command.sdist import sdist
+from setuptools import Command
from pathlib import Path
@@ -43,7 +44,59 @@ class CustomSdistCommand(sdist):
for path, contents in locale_files.items():
path.write_bytes(contents)
+class BuildDocCommand(Command):
+ """
+ Command to create an `htmldoc/` catalog with Haketilo documentation inside
+ as standalone .html files.
+ """
+ user_options = []
+
+ def run (self, *args, **kwargs):
+ """Generate the .html files"""
+ import jinja2
+ import shutil
+ import sys
+
+ htmldoc_dir = here / 'htmldoc'
+ if htmldoc_dir.exists():
+ shutil.rmtree(htmldoc_dir)
+
+ proxy_doc_dir = htmldoc_dir / 'haketilo'
+
+ sys.path.insert(0, str(here / 'src'))
+
+ from hydrilla.proxy import self_doc
+ from hydrilla import common_jinja_templates
+
+ loader = common_jinja_templates.combine_with_loaders([self_doc.loader])
+ jinja_env = jinja2.Environment(
+ loader = loader,
+ autoescape = jinja2.select_autoescape(['html.jinja']),
+ lstrip_blocks = True,
+ extensions = ['jinja2.ext.do']
+ )
+
+ for locale in self_doc.available_locales:
+ doc_dir = proxy_doc_dir / locale
+ doc_dir.mkdir(parents=True)
+
+ for page_name in self_doc.page_names:
+ file_name = f'{locale}/{page_name}.html.jinja'
+ template = jinja_env.get_template(file_name)
+ html_text = template.render(doc_output='html')
+
+ out_name = 'index' if page_name == 'doc_index' else page_name
+
+ (doc_dir / f'{out_name}.html').write_text(html_text)
+
+ def initialize_options(self):
+ pass
+
+ def finalize_options(self):
+ pass
+
setuptools.setup(cmdclass = {
- 'build_py': CustomBuildCommand,
- 'sdist': CustomSdistCommand
+ 'build_py': CustomBuildCommand,
+ 'sdist': CustomSdistCommand,
+ 'build_htmldoc': BuildDocCommand
})
diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py
index 838df57..eb5e9fd 100644
--- a/src/hydrilla/proxy/self_doc.py
+++ b/src/hydrilla/proxy/self_doc.py
@@ -16,6 +16,12 @@ loader = jinja2.PackageLoader(__package__, package_path='self_doc')
suffix_len = len('.html.jinja')
page_names = frozenset(
path.name[:-suffix_len]
- for path in (here / 'self_doc').glob('*.html.jinja')
+ for path in (here / 'self_doc/en_US').glob('*.html.jinja')
if path.name != 'doc_base.html.jinja'
)
+
+available_locales = tuple(
+ path.name
+ for path in (here / 'self_doc').iterdir()
+ if path.is_dir()
+)
diff --git a/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja b/src/hydrilla/proxy/self_doc/en_US/advanced_ui_features.html.jinja
index 045309b..045309b 100644
--- a/src/hydrilla/proxy/self_doc/advanced_ui_features.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/advanced_ui_features.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/doc_index.html.jinja b/src/hydrilla/proxy/self_doc/en_US/doc_index.html.jinja
index 03f2231..03f2231 100644
--- a/src/hydrilla/proxy/self_doc/doc_index.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/doc_index.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/packages.html.jinja b/src/hydrilla/proxy/self_doc/en_US/packages.html.jinja
index 23e6f45..23e6f45 100644
--- a/src/hydrilla/proxy/self_doc/packages.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/packages.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja
index 687d2bd..687d2bd 100644
--- a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/policy_selection.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/popup.html.jinja b/src/hydrilla/proxy/self_doc/en_US/popup.html.jinja
index a5ad909..a5ad909 100644
--- a/src/hydrilla/proxy/self_doc/popup.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/popup.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/repositories.html.jinja b/src/hydrilla/proxy/self_doc/en_US/repositories.html.jinja
index 4cf6d2c..4cf6d2c 100644
--- a/src/hydrilla/proxy/self_doc/repositories.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/repositories.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja
index c0a5275..c0a5275 100644
--- a/src/hydrilla/proxy/self_doc/script_blocking.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/script_blocking.html.jinja
diff --git a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja b/src/hydrilla/proxy/self_doc/en_US/url_patterns.html.jinja
index f3415c5..f3415c5 100644
--- a/src/hydrilla/proxy/self_doc/url_patterns.html.jinja
+++ b/src/hydrilla/proxy/self_doc/en_US/url_patterns.html.jinja
diff --git a/src/hydrilla/proxy/web_ui/root.py b/src/hydrilla/proxy/web_ui/root.py
index 4eea860..4915e51 100644
--- a/src/hydrilla/proxy/web_ui/root.py
+++ b/src/hydrilla/proxy/web_ui/root.py
@@ -188,14 +188,10 @@ def home_doc(page: str) -> str:
if page not in self_doc.page_names:
flask.abort(404)
- locale = translations.select_best_locale()
- if locale == translations.default_locale:
- prefix = ''
- else:
- prefix = f'{locale}/'
+ locale = translations.select_best_locale(self_doc.available_locales)
return flask.render_template(
- f'{prefix}{page}.html.jinja',
+ f'{locale}/{page}.html.jinja',
doc_output = 'html_hkt_mitm_it'
)
diff --git a/src/hydrilla/translations.py b/src/hydrilla/translations.py
index 62c8c88..1ff8788 100644
--- a/src/hydrilla/translations.py
+++ b/src/hydrilla/translations.py
@@ -39,7 +39,7 @@ supported_locales = [f.name for f in localedir.iterdir() if f.is_dir()]
default_locale = 'en_US'
-def select_best_locale() -> str:
+def select_best_locale(supported: t.Iterable[str] = supported_locales) -> str:
"""
....
@@ -56,8 +56,8 @@ def select_best_locale() -> str:
if use_flask:
best = flask.request.accept_languages.best_match(
- supported_locales,
- default=default_locale
+ supported,
+ default = default_locale
)
assert best is not None
return best
@@ -72,7 +72,7 @@ def select_best_locale() -> str:
except:
pass
- return locale if locale in supported_locales else default_locale
+ return locale if locale in supported else default_locale
translations: t.Dict[str, gettext.NullTranslations] = {}