MonkeyPatch how Sphinx handle numbered references

Sphinx treats references globally, so if the toctree is not numbered
the counting increments across the pages.

This patch changes this behaviour to always reset the count per page.
Bump version.

Signed-off-by: Jorge Marques <[email protected]>

adi_doctools/__init__.py

@@ -11,8 +11,9 @@
 from .role import setup as role_setup
 from .lut import get_lut
 from .role.interref import interref_repos_apply
+from .monkeypatch import monkeypatch_figure_numbers
 
-__version__ = "0.3.48"
+__version__ = "0.3.49"
 
 logger = logging.getLogger(__name__)
 
@@ -54,6 +55,10 @@ def html_page_context(app, pagename, templatename, context, doctree):
 
 
 def config_inited(app, config):
+
+    if config.numfig_per_doc:
+        monkeypatch_figure_numbers()
+
     app.lut = get_lut()
 
     interref_repos_apply(app)
@@ -130,6 +135,8 @@ def setup(app):
     app.connect("html-page-context", html_page_context)
     app.connect("build-finished", build_finished)
 
+    app.add_config_value('numfig_per_doc', False, 'env', [str])
+
     return {
         "parallel_read_safe": True,
         "parallel_write_safe": True,

adi_doctools/monkeypatch/__init__.py

@@ -0,0 +1,22 @@
+from sphinx.environment.collectors.toctree import TocTreeCollector
+
+def monkeypatch_figure_numbers():
+    """
+    Reset reference counting per page, even when the toctree is not numbered.
+    If the toctree is numbered, the offset should resolve as 0.
+    """
+    old_assign_figure_numbers = TocTreeCollector.assign_figure_numbers
+
+    def assign_figure_numbers(self, env):
+        rewrite_needed = old_assign_figure_numbers(self, env)
+        for entry in env.toc_fignumbers:
+            for type_ in  env.toc_fignumbers[entry]:
+                if len(env.toc_fignumbers[entry][type_]) > 0:
+                    offset = env.toc_fignumbers[entry][type_][next(iter(env.toc_fignumbers[entry][type_]))][-1] - 1
+                    for id_ in env.toc_fignumbers[entry][type_]:
+                        tuple_ = list(env.toc_fignumbers[entry][type_][id_])
+                        tuple_[-1] = tuple_[-1]-offset
+                        env.toc_fignumbers[entry][type_][id_] = tuple(tuple_)
+        return rewrite_needed
+
+    TocTreeCollector.assign_figure_numbers = assign_figure_numbers

adi_doctools/theme/cosmic/style/bundle.scss

@@ -11,3 +11,6 @@
 @import "related";
 @import "code";
 @import "print";
+@import "caption";
+@import "directive";
+@import "table";

adi_doctools/theme/cosmic/style/caption.scss

@@ -0,0 +1,9 @@
+.caption-number {
+    color: var(--text-color2);
+}
+
+.caption-number:after {
+    content: ':';
+    margin-left: -.3em;
+    margin-right: .2em;
+}

adi_doctools/theme/cosmic/style/element.scss

@@ -23,6 +23,7 @@ span {
 
 :is(h1, h2, h3, h4, h5, h6) .headerlink,
 figure .headerlink {
+    user-select: none;
     margin-left: .25em;
     opacity: 0;
     transition: opacity ease .125s;
@@ -76,45 +77,6 @@ a {
     overflow-x: auto;
 }
 
-.table-wrapper {
-    margin-bottom: .5em;
-}
-
-table.docutils {
-    border-spacing: 0;
-    border-radius: $border-radius;
-    border: $border-td;
-
-    thead {
-        background-color: var(--bg-color2);
-    }
-
-    th {
-        border-bottom: $border-th;
-    }
-
-    td {
-        border-bottom: $border-td;
-    }
-
-    p {
-        margin: 0;
-        text-align: left;
-    }
-
-    th, td {
-        padding: .5em;
-    }
-
-    tr:last-child td {
-        border: none;
-    }
-
-    thead:not(:first-child) th {
-        font-weight: normal;
-    }
-}
-
 img {
     display: block;
     margin: 0 auto;
@@ -128,7 +90,7 @@ img {
 }
 
 @media print, (min-width: $screen-1) {
-    .body img {
+    .body img, .body figure {
         display: block;
         margin: 0 auto;
         max-width: 100%;

adi_doctools/theme/cosmic/style/related.scss

@@ -10,6 +10,7 @@
     a {
         display: flex;
         align-items: center;
+        max-width: 50%;
     }
 
     .prev {

adi_doctools/theme/cosmic/style/table.scss

@@ -0,0 +1,44 @@
+.table-wrapper {
+    margin-bottom: .5em;
+}
+
+table.docutils {
+    border-spacing: 0;
+    border-radius: $border-radius;
+    border: $border-td;
+
+    thead {
+        background-color: var(--bg-color2);
+    }
+
+    th {
+        border-bottom: $border-th;
+    }
+
+    td {
+        border-bottom: $border-td;
+    }
+
+    p {
+        margin: 0;
+        text-align: left;
+    }
+
+    th, td {
+        padding: .5em;
+    }
+
+    tr:last-child td {
+        border-bottom: none;
+    }
+
+    thead:not(:first-child) th {
+        font-weight: normal;
+    }
+
+    &.grid {
+        td:not(:first-child), th:not(:first-child) {
+            border-left: $border-td;
+        }
+    }
+}

docs/docs_guidelines.rst

@@ -204,6 +204,37 @@ and always lower case,
 for example
 ``my_code control-interface`` instead of ``MY_CODE Control_Interface``.
 
+Numbered references
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+References can be numbered by using
+`numref <https://www.sphinx-doc.org/en/master/usage/referencing.html#role-numref>`__,
+for example, "*see Figure 1*".
+
+To use this feature, enable on the *conf.py*:
+
+.. code-block:: python
+
+   numfig = True
+
+To customize the format, set ``numfig_format``:
+
+.. code-block:: python
+
+   numfig_format = {'figure': 'Figure %s',
+                    'table': 'Table %s',
+                    'code-block': 'Listing %s',
+                    'section': 'Section %s'}
+
+.. tip::
+
+   By default enumeration is global, so if the toctree is not
+   `numbered <https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-option-toctree-numbered>`__ to divide the pages in numbered sections (e.g. *Figure 3.4.4*),
+   the numbering will "propagate" across page which may be counter-intuitive.
+
+   To have the numbering reset at every page, add ``numfig_per_doc = True`` to
+   *conf.py*.
+
 .. _inter-refs:
 
 External references