From cd5763043299d3f48f1bfc4b87a5cb251949f904 Mon Sep 17 00:00:00 2001
From: Tomas Krizek <tomas.krizek@nic.cz>
Date: Fri, 11 Dec 2020 15:42:22 +0100
Subject: [PATCH] doc: use :any: to refer to non-function policies
:func: directive automatically always adds brackets. This results in
links such as "policy.PASS()", which can be confusing, since the actual
policy is supposed to be "policy.PASS".
Using :any: results in links without the added brackets, which makes
non-function policies less confusing.
---
modules/hints/README.rst | 2 +-
modules/policy/README.rst | 20 ++++++++++----------
2 files changed, 11 insertions(+), 11 deletions(-)
diff --git a/modules/hints/README.rst b/modules/hints/README.rst
index def8d24a4..65bebaa16 100644
--- a/modules/hints/README.rst
+++ b/modules/hints/README.rst
@@ -33,7 +33,7 @@ Examples
hints['foo.bar'] = '127.0.0.1'
.. note:: The :ref:`policy <mod-policy>` module applies before hints, meaning e.g. that hints for special names (:rfc:`6761#section-6`) like ``localhost`` or ``test`` will get shadowed by policy rules by default.
- That can be worked around e.g. by explicit ``policy.PASS`` action.
+ That can be worked around e.g. by explicit :any:`policy.PASS` action.
Properties
----------
diff --git a/modules/policy/README.rst b/modules/policy/README.rst
index dbcc5064d..8d4a7f064 100644
--- a/modules/policy/README.rst
+++ b/modules/policy/README.rst
@@ -13,11 +13,11 @@ This module can block, rewrite, or alter inbound queries based on user-defined p
Each policy *rule* has two parts: a *filter* and an *action*. A *filter* selects which queries will be affected by the policy, and *action* which modifies queries matching the associated filter.
-Typically a rule is defined as follows: ``filter(action(action parameters), filter parameters)``. For example, a filter can be ``suffix`` which matches queries whose suffix part is in specified set, and one of possible actions is ``DENY``, which denies resolution. These are combined together into ``policy.suffix(policy.DENY, {todname('badguy.example.')})``. The rule is effective when it is added into rule table using ``policy.add()``, please see examples below.
+Typically a rule is defined as follows: ``filter(action(action parameters), filter parameters)``. For example, a filter can be ``suffix`` which matches queries whose suffix part is in specified set, and one of possible actions is :any:`policy.DENY`, which denies resolution. These are combined together into ``policy.suffix(policy.DENY, {todname('badguy.example.')})``. The rule is effective when it is added into rule table using ``policy.add()``, please see examples below.
This module is enabled by default because it implements mandatory :rfc:`6761` logic.
When no rule applies to a query, built-in rules for `special-use <https://www.iana.org/assignments/special-use-domain-names/special-use-domain-names.xhtml>`_ and `locally-served <http://www.iana.org/assignments/locally-served-dns-zones>`_ domain names are applied.
-These rules can be overriden by action :func:`policy.PASS`. For debugging purposes you can also add ``modules.unload('policy')`` to your config to unload the module.
+These rules can be overriden by action :any:`policy.PASS`. For debugging purposes you can also add ``modules.unload('policy')`` to your config to unload the module.
Filters
@@ -80,7 +80,7 @@ It is also possible to define custom filter function with any name.
end
This custom filter can be used as any other built-in filter.
-For example this applies our custom filter and executes action :func:`policy.DENY` on all queries of type `HINFO`:
+For example this applies our custom filter and executes action :any:`policy.DENY` on all queries of type `HINFO`:
.. code-block:: lua
@@ -221,7 +221,7 @@ Following actions act on request and then processing continue until first non-ch
.. py:data:: DEBUG_CACHE_MISS
- Enable extra verbose logging but print logs only for requests which required information which was not available locally (i.e. requests which forced resolver to communicate over network). Intended usage is for debugging problems with remote servers. This action typically produces less logs than :func:`policy.DEBUG_ALWAYS` but all caveats from :func:`policy.DEBUG_IF` apply as well.
+ Enable extra verbose logging but print logs only for requests which required information which was not available locally (i.e. requests which forced resolver to communicate over network). Intended usage is for debugging problems with remote servers. This action typically produces less logs than :any:`policy.DEBUG_ALWAYS` but all caveats from :func:`policy.DEBUG_IF` apply as well.
.. code-block:: lua
@@ -567,20 +567,20 @@ Response policy zones
.. csv-table::
:header: "RPZ Right Hand Side", "Knot Resolver Action", "BIND Compatibility"
- "``.``", "``action`` is used", "compatible if ``action`` is :func:`policy.DENY`"
+ "``.``", "``action`` is used", "compatible if ``action`` is :any:`policy.DENY`"
"``*.``", ":func:`policy.ANSWER`", "yes"
- "``rpz-passthru.``", ":func:`policy.PASS`", "yes"
- "``rpz-tcp-only.``", ":func:`policy.TC`", "yes"
- "``rpz-drop.``", ":func:`policy.DROP`", "no [#]_"
+ "``rpz-passthru.``", ":any:`policy.PASS`", "yes"
+ "``rpz-tcp-only.``", ":any:`policy.TC`", "yes"
+ "``rpz-drop.``", ":any:`policy.DROP`", "no [#]_"
"fake A/AAAA", ":func:`policy.ANSWER`", "yes"
"fake CNAME", "not supported", "no"
- .. [#] Our :func:`policy.DROP` returns *SERVFAIL* answer (for historical reasons).
+ .. [#] Our :any:`policy.DROP` returns *SERVFAIL* answer (for historical reasons).
.. function:: rpz(action, path, [watch = true])
- :param action: the default action for match in the zone; typically you want :func:`policy.DENY`
+ :param action: the default action for match in the zone; typically you want :any:`policy.DENY`
:param path: path to zone file
:param watch: boolean, if true, the file will be reloaded on file change
--
GitLab