[proxy] document policy selection

6 files changed, 116 insertions, 6 deletions

diff --git a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
index 0785039..ccdc7c8 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/info_base.html.jinja
@@ -20,6 +20,11 @@ code in a proprietary work, I am not going to enforce this in court.
 #}
 {% extends "base.html.jinja" %}
 
+{% macro hkt_doc_link(page_name) %}
+  {% set doc_url = 'https://hkt.mitm.it/doc/' ~ page_name %}
+  {{ doc_link(doc_url) }}
+{% endmacro %}
+
 {% block style %}
   {{ super() }}
 
@@ -47,7 +52,9 @@ code in a proprietary work, I am not going to enforce this in court.
 
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.base.page_policy_label')) }}
+  {% call label(_('info.base.page_policy_label')) %}
+    {{ hkt_doc_link('policy_selection') }}
+  {% endcall %}
 
   <p class="has-colored-links">
     {% block site_policy required %}{% endblock %}
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
index b808827..1c0c662 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/js_rule_info.html.jinja
@@ -29,7 +29,9 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block main_rest %}
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.rule.matched_pattern_label')) }}
+  {% call label(_('info.rule.matched_pattern_label')) %}
+    {{ hkt_doc_link('url_patterns') }}
+  {% endcall %}
 
   <p>
     {{ pattern }}
diff --git a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
index a71ca25..e66e685 100644
--- a/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
+++ b/src/hydrilla/proxy/policies/info_pages_templates/payload_info.html.jinja
@@ -40,7 +40,9 @@ code in a proprietary work, I am not going to enforce this in court.
 {% block main_rest %}
   <div class="horizontal-separator"></div>
 
-  {{ label(_('info.payload.matched_pattern_label')) }}
+  {% call label(_('info.payload.matched_pattern_label')) %}
+    {{ hkt_doc_link('url_patterns') }}
+  {% endcall %}
 
   <p>
     {{ payload_data.pattern }}
diff --git a/src/hydrilla/proxy/self_doc.py b/src/hydrilla/proxy/self_doc.py
index a1a2485..ccf0e12 100644
--- a/src/hydrilla/proxy/self_doc.py
+++ b/src/hydrilla/proxy/self_doc.py
@@ -8,4 +8,4 @@ import jinja2
 
 loader = jinja2.PackageLoader(__package__, package_path='self_doc')
 
-page_names = {'url_patterns'}
+page_names = {'url_patterns', 'policy_selection'}
diff --git a/src/hydrilla/proxy/self_doc/doc_base.html.jinja b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
index 7982142..71842f2 100644
--- a/src/hydrilla/proxy/self_doc/doc_base.html.jinja
+++ b/src/hydrilla/proxy/self_doc/doc_base.html.jinja
@@ -36,8 +36,20 @@ code in a proprietary work, I am not going to enforce this in court.
   {{ caller()|safe }}
 {% endmacro %}
 
-{% macro link(where, text) -%}
-  <a href="{{ where }}">{{ text }}</a>
+{% macro doc_page_link(text, page_name) -%}
+  {% if doc_output == 'html_hkt_mitm_it' -%}
+    <a href="{{ url_for('.home_doc', page=page_name) }}">{{ text }}</a>
+  {%- else -%}
+    <a href="{{ page_name ~ '.html' }}">{{ text }}</a>
+  {%- endif %}
+{%- endmacro %}
+
+{% macro hkt_link(text, endpoint_name) -%}
+  {% if doc_output == 'html_hkt_mitm_it' -%}
+    <a href="{{ url_for(endpoint_name, **kwargs) }}">{{ text }}</a>
+  {%- else -%}
+    {{ text }}
+  {%- endif %}
 {%- endmacro %}
 
 {% macro paragraph() %}
diff --git a/src/hydrilla/proxy/self_doc/policy_selection.html.jinja b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
new file mode 100644
index 0000000..6519e42
--- /dev/null
+++ b/src/hydrilla/proxy/self_doc/policy_selection.html.jinja
@@ -0,0 +1,87 @@
+{#
+SPDX-License-Identifier: GPL-3.0-or-later OR CC-BY-SA-4.0
+
+Documentation page describing how Haketilo selects policy to apply to a page.
+
+This file is part of Hydrilla&Haketilo.
+
+Copyright (C) 2022 Wojtek Kosior
+
+Dual licensed under
+* GNU General Public License v3.0 or later and
+* Creative Commons Attribution Share Alike 4.0 International.
+
+You can choose to use either of these licenses or both.
+
+
+I, Wojtek Kosior, thereby promise not to sue for violation of this
+file's licenses. Although I request that you do not make use of this
+code in a proprietary work, I am not going to enforce this in court.
+#}
+{% extends "doc_base.html.jinja" %}
+
+{% block title %}{{ _('doc.policy_selection.title') }}{% endblock %}
+
+{% block main %}
+  {{ big_heading(_('doc.policy_selection.h_big')) }}
+
+  {% call section() %}
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.intro') }}
+      {% call unordered_list() %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.enabled_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.auto_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.ask_payload_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.block_js_case') }}
+        {% endcall %}
+        {% call list_entry() %}
+          {{ _('doc.policy_selection.allow_js_case') }}
+        {% endcall %}
+      {% endcall %}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.policy_selection.h_medium.precedence')) }}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.policy_selection.html.precedence_general_{patterns_link}') %}
+      {% set link_text = _('doc.policy_selection.precedence_general.patterns_link_text') %}
+      {% set link = doc_page_link(link_text|e, 'url_patterns') %}
+      {{ fmt.format(patterns_link=link)|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.policy_selection.html.precedence_nonenabled_{settings_link}') %}
+      {% set link_text = _('doc.policy_selection.precedence_nonenabled.settings_link_text') %}
+      {% set link = hkt_link(link_text|e, 'home.home') %}
+      {{ fmt.format(settings_link=link)|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {% set fmt = _('doc.policy_selection.html.precedence_fallback_{settings_link}') %}
+      {% set link_text = _('doc.policy_selection.precedence_fallback.settings_link_text') %}
+      {% set link = hkt_link(link_text|e, 'home.home') %}
+      {{ fmt.format(settings_link=link)|safe }}
+    {% endcall %}
+  {% endcall %}
+
+  {% call section() %}
+    {{ medium_heading(_('doc.policy_selection.special_cases.h_medium')) }}
+
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.special_cases.html.exepmt_and_error')|safe }}
+    {% endcall %}
+
+    {% call paragraph() %}
+      {{ _('doc.policy_selection.special_cases.internal_policies') }}
+    {% endcall %}
+  {% endcall %}
+{% endblock main %}