From 441260bea353713e935ee8daf3a77596b6600cca Mon Sep 17 00:00:00 2001 From: gwen Date: Wed, 3 Jun 2026 21:03:47 +0200 Subject: [PATCH] docs(132-practice-url-error): and validators continuation --- docs/documentation.rst | 8 +++----- docs/tutorial/practice1.rst | 6 +++--- docs/tutorial/validators.rst | 23 ++++++++++++++++++++--- 3 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/documentation.rst b/docs/documentation.rst index 31b6cc794..c5db5eeee 100644 --- a/docs/documentation.rst +++ b/docs/documentation.rst @@ -38,8 +38,8 @@ Example: Do **not** skip levels (e.g. going from a level 1 title directly to a level 3 heading). -Handling TODOs -------------------- +Handling TODOs and FIXMEs +------------------------------ We use two complementary mechanisms to track pending work: @@ -47,6 +47,7 @@ We use two complementary mechanisms to track pending work: - **``.. todo::`` directive** – for things that need to be **done** (missing sections, improvements, new features) Example: + .. code-block:: rst FIXME: The example below uses a deprecated function. @@ -175,7 +176,6 @@ Explanation of options: - **``:language: yaml``** – enables YAML syntax highlighting in the rendered output - **``:caption: ``** – adds a descriptive caption below the code block -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Displaying terminal commands ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -189,7 +189,6 @@ To include and display a text file containing bash commands or terminal output, This fetches the remote text file and renders it with terminal-style formatting (typically a dark background, monospaced font, and command-line appearance). -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Displaying HTML output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -203,7 +202,6 @@ To include and display an HTML file from the remote forge, use the ``raw`` direc This fetches the remote HTML file and embeds it directly into the generated documentation page. -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Summary ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/docs/tutorial/practice1.rst b/docs/tutorial/practice1.rst index a91900f43..cfe0202aa 100644 --- a/docs/tutorial/practice1.rst +++ b/docs/tutorial/practice1.rst @@ -110,15 +110,15 @@ Our solution .. type-along:: For those who follow the tutorial with the help of the git repository - Now you need to checkout the :tutorial:`v1.1_131 ` version:: + Now you need to checkout the :tutorial:`v1.1_132 ` version:: - git switch --detach v1.1_131 + git switch --detach v1.1_132 Please unroll the "Solution" widget to see our solution: .. solution:: Solution - .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_131/firefox/55-proxy_dns_socks5.yml + .. extinclude:: https://forge.cloud.silique.fr/stove/rougail-tutorials/raw/commit/v1.1_132/firefox/55-proxy_dns_socks5.yml :language: yaml :caption: The :file:`firefox/55-proxy_dns_socks5.yml` a Jinja conditional disabled boolean variable diff --git a/docs/tutorial/validators.rst b/docs/tutorial/validators.rst index bd6358e77..d96b2edf9 100644 --- a/docs/tutorial/validators.rst +++ b/docs/tutorial/validators.rst @@ -27,15 +27,32 @@ Validating a variable's value A variable with custom validation ----------------------------------- -Now, we would like the :term:`operator` to remember not to forget the http protocol, that is to put `http://` at the beginning of our `web_address` variable's value. What if he has forgotten the http protocol? We can add a reminder in case he has forgotten. +First, we would like the :term:`operator` to remember not to forget the http protocol, that is to put `http://` at the beginning of our `web_address` variable's value. +Actually the `web_address`\ 's type requires that the address include the HTTP protocol, namely: -We call it a validator. +:: + + http(s):// + + +However, in our use case, we want *to force* the HTTPS protocol. +We don't want `http://`, only `https://`. + +.. note:: This URL is for DNS over HTTPS, providing greater privacy than using the ISP's DNS, + which can filter traffic. If it uses `http://`, it doesn't make sense. + +But there's no existing type for this specific use case (forcing HTTPS). + +We just said that a valid value must start with `https://` instead of `http://`. +It is possible, instead of creating a new type, to add custom validation of the variable's value. + +We call it a :term:`validator`. .. glossary:: validator - A validator is a jinja code that parses a variable's value and checks + A validator is a Jinja code that parses a variable's value and checks that this value corresponds to some stated criteria. This is a `validator` parameter of our variable, and another `jinja` sub-parameter contains validation code for the variable's value.