docs: issue2551317 add support for jinja2 customization examples

Added sphinx-tabs to doc build. This allows adding code-tabs one for
"TAL" examples and one for "Jinja2" examples in the doc.

Converted partly the "Editing multiple items in an index view"
example.  Sombody who knows jinja2 better than I, and can test the
example will need to finish it.

Documented requirement and method for building docs in developers.txt.
Added requirements.pip files for pip install -r ... modules needed for
processing docs.

Fixed missing block in layout.txt that stopped tabs.css from being
loaded.

Author: rouilj

CHANGES.txt

@@ -110,6 +110,8 @@ Features:
 - issue2551274: add configurable logging for REST API when something
   fails, we now log status code and error message.
   (Ralf Schlatterbeck)
+- issue2551317 - add some Jinja2 examples to customizing.txt
+  document. (John Rouillard)
 
 2023-07-13 2.3.0
 

doc/conf.py

@@ -51,6 +51,10 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 #extensions = ['toctree']
+extensions = ['sphinx_tabs.tabs']
+
+sphinx_tabs_valid_builders = ['linkcheck']
+sphinx_tabs_disable_tab_closing = True
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

doc/customizing.txt

@@ -1864,43 +1864,82 @@ To edit the status of all items in the item index view, edit the
 ``issue.index.html``:
 
 1. add a form around the listing table (separate from the existing
-   index-page form), so at the top it reads::
+   index-page form), so at the top it reads:
 
-    <form method="POST" tal:attributes="action request/classname">
-     <table class="list">
+   .. tabs::
 
-   and at the bottom of that table::
+      .. code-tab:: html TAL
+
+        <form method="POST" tal:attributes="action request/classname">
+        <table class="list">
+
+      .. code-tab:: html Jinja2
+
+         <form method="POST" action='issue{{ context.id }}' class='form-inline'>
+         <table class="list">
+
+
+   and at the bottom of that table add::
 
      </table>
     </form
 
    making sure you match the ``</table>`` from the list table, not the
    navigation table or the subsequent form table.
 
-2. in the display for the issue property, change::
+2. in the display for the issue property, change:
 
-    <td tal:condition="request/show/status"
-        tal:content="python:i.status.plain() or default">&nbsp;</td>
+   .. tabs::
 
-   to::
+      .. code-tab:: html TAL
+
+         <td tal:condition="request/show/status"
+            tal:content="python:i.status.plain() or default">&nbsp;</td>
+
+      .. code-tab:: html Jinja2
+
+         {% if request.show.status %}
+         <td>{{ issue.status.plain()|u }}</td>
+         {% endif %}
+
+   to:
+
+   .. tabs::
 
-    <td tal:condition="request/show/status"
-        tal:content="structure i/status/field">&nbsp;</td>
+      .. code-tab:: html TAL
 
+         <td tal:condition="request/show/status"
+            tal:content="structure i/status/field">&nbsp;</td>
+
+      .. code-tab:: html Jinja2
+
+         {% if request.show.status %}
+         <td>{{ issue.status.menu()|u|safe }}</td>
+         {% endif %}
+         <!-- untested -->
+ 
    this will result in an edit field for the status property.
 
 3. after the ``tal:block`` which lists the index items (marked by
-   ``tal:repeat="i batch"``) add a new table row::
+   ``tal:repeat="i batch"``) add a new table row:
 
-    <tr>
-     <td tal:attributes="colspan python:len(request.columns)">
-      <input name="@csrf" type="hidden"		
-           tal:attributes="value python:utils.anti_csrf_nonce()">
-      <input type="submit" value=" Save Changes ">
-      <input type="hidden" name="@action" value="edit">
-      <tal:block replace="structure request/indexargs_form" />
-     </td>
-    </tr>
+   .. tabs::
+
+      .. code-tab:: html TAL
+
+	 <tr>
+	  <td tal:attributes="colspan python:len(request.columns)">
+	   <input name="@csrf" type="hidden"		
+		tal:attributes="value python:utils.anti_csrf_nonce()">
+	   <input type="submit" value=" Save Changes ">
+	   <input type="hidden" name="@action" value="edit">
+	   <tal:block replace="structure request/indexargs_form" />
+	  </td>
+	 </tr>
+
+      .. code-tab:: html Jinja2
+
+         To Be Written
 
    which gives us a submit button, indicates that we are performing an
    edit on any changed statuses, and provides a defense against cross

doc/developers.txt

@@ -182,6 +182,26 @@ roundup will write each email message that it sends to that file
 instead to the internet.  This environment variable is independent of
 the python -O flag.
 
+Documentation Notes
+-------------------
+
+All docs are written using sphinx. Use pip or your package manager to
+install sphinx. In addition you will need to install a couple of
+sphinx extensions to process the files. A requirement's file can be
+found in docs/requirement.pip or website/www/requirements.pip. You can
+install these requirements using ``python -m pip install -r
+<path_to_requirements_file>``.
+
+The extensions sphinx-sitemap generates a sitemap when building for
+the website. The sphinx-tabs extension generates tabs for displaying
+code examples in both TAL and Jinja2.
+
+To build the documentation distributed with a Roundup release, run
+``python setup.py build_doc`` at the root of the source tree. To build
+docs for the website, see the ``updating www.roundup-tracker.org``
+section of ``website/README.txt`` or TL;DR ``cd website/www; make
+html``.
+
 Testing Notes
 -------------
 

doc/requirements.pip

@@ -0,0 +1 @@
+sphinx-tabs

website/www/_templates/layout.html

@@ -133,6 +133,10 @@
     </footer>
 {%- endblock %}
     <link rel="stylesheet" href="{{ pathto('_static/pygments.css', 1) }}" type="text/css" />
+    {%- for cssfile in css_files %}
+    <!-- loading css_files -->
+    <link rel="stylesheet" href="{{ pathto(cssfile, 1) }}" type="text/css" />
+    {%- endfor %}
     <script>
       /* locally hosted goatcounter https://www.goatcounter.com/ */
       /* include site info in path url to allow multiple sites to be

website/www/conf.py

@@ -43,7 +43,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx_sitemap']
+extensions = ['sphinx_sitemap', 'sphinx_tabs.tabs']
+
+sphinx_tabs_valid_builders = ['linkcheck']
+sphinx_tabs_disable_tab_closing = True
 
 # for sitemap default: "{lang}{version}subdir/{link}"
 sitemap_url_scheme = "{link}"

website/www/requirements.pip

@@ -1 +1,2 @@
-sphinx_sitemap
+sphinx-sitemap
+sphinx-tabs