From 4a2e63c41bba7aa0e1b7e074805b2aefbe4f6641 Mon Sep 17 00:00:00 2001 From: Jorge Marques Date: Fri, 25 Oct 2024 13:07:56 -0300 Subject: [PATCH] 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 --- adi_doctools/__init__.py | 9 +++- adi_doctools/monkeypatch/__init__.py | 22 ++++++++++ adi_doctools/theme/cosmic/style/bundle.scss | 3 ++ adi_doctools/theme/cosmic/style/caption.scss | 9 ++++ .../theme/cosmic/style/directive.scss | 0 adi_doctools/theme/cosmic/style/element.scss | 42 +----------------- adi_doctools/theme/cosmic/style/related.scss | 1 + adi_doctools/theme/cosmic/style/table.scss | 44 +++++++++++++++++++ docs/docs_guidelines.rst | 31 +++++++++++++ 9 files changed, 120 insertions(+), 41 deletions(-) create mode 100644 adi_doctools/monkeypatch/__init__.py create mode 100644 adi_doctools/theme/cosmic/style/caption.scss create mode 100644 adi_doctools/theme/cosmic/style/directive.scss create mode 100644 adi_doctools/theme/cosmic/style/table.scss diff --git a/adi_doctools/__init__.py b/adi_doctools/__init__.py index abaae40..cd98d74 100644 --- a/adi_doctools/__init__.py +++ b/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, diff --git a/adi_doctools/monkeypatch/__init__.py b/adi_doctools/monkeypatch/__init__.py new file mode 100644 index 0000000..b55efe0 --- /dev/null +++ b/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 diff --git a/adi_doctools/theme/cosmic/style/bundle.scss b/adi_doctools/theme/cosmic/style/bundle.scss index 23e1023..33fff01 100644 --- a/adi_doctools/theme/cosmic/style/bundle.scss +++ b/adi_doctools/theme/cosmic/style/bundle.scss @@ -11,3 +11,6 @@ @import "related"; @import "code"; @import "print"; +@import "caption"; +@import "directive"; +@import "table"; diff --git a/adi_doctools/theme/cosmic/style/caption.scss b/adi_doctools/theme/cosmic/style/caption.scss new file mode 100644 index 0000000..41279df --- /dev/null +++ b/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; +} diff --git a/adi_doctools/theme/cosmic/style/directive.scss b/adi_doctools/theme/cosmic/style/directive.scss new file mode 100644 index 0000000..e69de29 diff --git a/adi_doctools/theme/cosmic/style/element.scss b/adi_doctools/theme/cosmic/style/element.scss index a684665..24df181 100644 --- a/adi_doctools/theme/cosmic/style/element.scss +++ b/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%; diff --git a/adi_doctools/theme/cosmic/style/related.scss b/adi_doctools/theme/cosmic/style/related.scss index fdd94ff..e8e5c06 100644 --- a/adi_doctools/theme/cosmic/style/related.scss +++ b/adi_doctools/theme/cosmic/style/related.scss @@ -10,6 +10,7 @@ a { display: flex; align-items: center; + max-width: 50%; } .prev { diff --git a/adi_doctools/theme/cosmic/style/table.scss b/adi_doctools/theme/cosmic/style/table.scss new file mode 100644 index 0000000..2906f08 --- /dev/null +++ b/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; + } + } +} diff --git a/docs/docs_guidelines.rst b/docs/docs_guidelines.rst index 6b1d02c..3d16a4d 100644 --- a/docs/docs_guidelines.rst +++ b/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 `__, +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 `__ 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