[proxy] make it possible to export embedded documentation as standalone .html files and include these in the binary release tarball

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] = {}