From 46f26542ec51b3e4f0e442e8fa1c9758f1720829 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:02:31 -0700 Subject: [PATCH 01/31] patch literal blocks captions; add result directive --- docs/_static/results.css | 16 +++++++ sphinx_immaterial/__init__.py | 2 + sphinx_immaterial/patch_literal_blocks.py | 58 +++++++++++++++++++++++ sphinx_immaterial/theme_result.py | 54 +++++++++++++++++++++ src/assets/stylesheets/main/_api.scss | 7 +++ 5 files changed, 137 insertions(+) create mode 100644 docs/_static/results.css create mode 100644 sphinx_immaterial/patch_literal_blocks.py create mode 100644 sphinx_immaterial/theme_result.py diff --git a/docs/_static/results.css b/docs/_static/results.css new file mode 100644 index 000000000..853c7429d --- /dev/null +++ b/docs/_static/results.css @@ -0,0 +1,16 @@ +/* **************************** theme-results directive special ******************** */ + +.md-typeset .code-block-caption+.notranslate pre, +.md-typeset .code-block-caption+.notranslate>.highlighttable { + margin-top: 0; +} + +.result .results-prefix { + margin-bottom: 1em; + margin-top: 0.1rem; + background-color: var(--md-code-bg-color); + overflow: visible; + border-bottom-left-radius: 0.5rem; + border-bottom-right-radius: 0.5rem; + padding: 0 0.5rem; +} diff --git a/sphinx_immaterial/__init__.py b/sphinx_immaterial/__init__.py index b7c6ad1b9..055b17ab3 100644 --- a/sphinx_immaterial/__init__.py +++ b/sphinx_immaterial/__init__.py @@ -20,6 +20,7 @@ from . import object_toc from . import postprocess_html from . import search_adapt +from . import patch_literal_blocks from .details_patch import monkey_patch_details_run logger = sphinx.util.logging.getLogger(__name__) @@ -276,6 +277,7 @@ def setup(app): app.setup_extension(inlinesyntaxhighlight.__name__) app.setup_extension(object_toc.__name__) app.setup_extension(search_adapt.__name__) + app.setup_extension(patch_literal_blocks.__name__) app.connect("html-page-context", html_page_context) app.connect("builder-inited", _builder_inited) app.add_config_value( diff --git a/sphinx_immaterial/patch_literal_blocks.py b/sphinx_immaterial/patch_literal_blocks.py new file mode 100644 index 000000000..dba4e2f81 --- /dev/null +++ b/sphinx_immaterial/patch_literal_blocks.py @@ -0,0 +1,58 @@ +"""A monkey patch to conform code-blocks to superfences' output.""" +from docutils import nodes +from sphinx.transforms.post_transforms.code import HighlightLanguageVisitor +from sphinx.writers.html5 import HTML5Translator +from sphinx.application import Sphinx +from sphinx.locale import _ + + +def re_visit_literal_block( + self: HighlightLanguageVisitor, node: nodes.literal_block +) -> None: + setting = self.settings[-1] + + node.parent["classes"] += ["highlight"] + if "language" not in node: + node["language"] = setting.language + node["force"] = setting.force + if "linenos" not in node: + lines = node.astext().count("\n") + node["linenos"] = lines >= setting.lineno_threshold - 1 + + +def re_visit_caption(self: HTML5Translator, node: nodes.Element) -> None: + attributes = {"class": "caption-text"} + if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): + self.body.append('
') + attributes["class"] += " filename" + else: + super().visit_caption(node) + self.add_fignumber(node.parent) + self.body.append(self.starttag(node, "span", **attributes)) + + +def re_depart_caption(self: HTML5Translator, node: nodes.Element) -> None: + if not isinstance(node.parent, nodes.container) and not node.parent.get( + "literal_block" + ): + self.body.append("") + + # append permalink if available + if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): + self.add_permalink_ref(node.parent, _("Permalink to this code")) + self.body.append("") + elif isinstance(node.parent, nodes.figure): + self.add_permalink_ref(node.parent, _("Permalink to this image")) + elif node.parent.get("toctree"): + self.add_permalink_ref(node.parent.parent, _("Permalink to this toctree")) + + if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): + self.body.append("
\n") + else: + super().depart_caption(node) + + +def setup(app: Sphinx): + HighlightLanguageVisitor.visit_literal_block = re_visit_literal_block + HTML5Translator.visit_caption = re_visit_caption + HTML5Translator.depart_caption = re_depart_caption diff --git a/sphinx_immaterial/theme_result.py b/sphinx_immaterial/theme_result.py new file mode 100644 index 000000000..2de660d8f --- /dev/null +++ b/sphinx_immaterial/theme_result.py @@ -0,0 +1,54 @@ +"""A directive designed to reduce example snippets duplication.""" +from docutils.parsers.rst import directives +from docutils import nodes +from sphinx.util.docutils import SphinxDirective +from sphinx.directives.code import container_wrapper + + +class ResultsDirective(SphinxDirective): + """Takes content as a rst code snippet and renders it after outputting it as a + literal code-block.""" + + has_content = True + optional_arguments = 1 + final_argument_whitespace = True + option_spec = { + "class": directives.class_option, + "name": directives.unchanged, + "output-prefix": directives.unchanged, + } + + def run(self): + """Run the directive.""" + container_node = nodes.container( + "", is_div=True, classes=self.options.get("class", []) + ["results"] + ) + code = "\n".join(self.content) + literal_node = nodes.literal_block( + code, code, caption="" if not self.arguments else self.arguments[0] + ) + literal_node["language"] = "rst" + literal_node["classes"] += ["highlight"] + if self.arguments: + literal_node = container_wrapper( + self, literal_node=literal_node, caption=self.arguments[0] + ) + results_div = nodes.container("", is_div=True, classes=["result"]) + if "output-prefix" in self.options: + out_prefix = nodes.container("", classes=["results-prefix"]) + prefix = self.options.get("output-prefix", "") + if not prefix: + prefix = "Which renders the following content:" + textnodes, _ = self.state.inline_text(prefix, self.lineno) + out_prefix += textnodes + results_div += out_prefix + self.state.nested_parse(self.content, self.content_offset, results_div) + container_node += literal_node + container_node += results_div + self.set_source_info(container_node) + self.add_name(container_node) + return [container_node] + + +def setup(app): + app.add_directive("result", ResultsDirective) diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index 0d9fb8eed..86104f7ed 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -222,3 +222,10 @@ table.longtable.docutils.data.align-default { } } } + +// a rule to reset margin for code-blocks with a caption +// works best with sphinx_immaterial.patch_literal_blocks extension +.md-typeset .code-block-caption + .notranslate pre, +.md-typeset .code-block-caption + .notranslate .highlighttable { + margin-top: 0; +} From 9b716b238ffb780f540f7e65040ab87b3d70e959 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:10:23 -0700 Subject: [PATCH 02/31] update docs for results directive --- docs/_static/extra_css.css | 5 +- docs/_static/results.css | 5 -- docs/admonitions.rst | 155 ++++++++++++++----------------------- docs/conf.py | 8 +- docs/content_tabs.rst | 41 +--------- docs/demo_api.rst | 133 ++++++++++++++++++------------- docs/index.rst | 2 +- docs/mermaid_diagrams.rst | 109 +++++--------------------- 8 files changed, 172 insertions(+), 286 deletions(-) diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index bdce350a5..ce1c49581 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -16,11 +16,14 @@ --md-icon__fa-gitlab: url('data:image/svg+xml;charset=utf-8,'); --md-icon__fa-gitkraken: url('data:image/svg+xml;charset=utf-8,'); --md-icon__fa-bitbucket: url('data:image/svg+xml;charset=utf-8,'); - --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,') } /* *************************** custom admonition style rules *************************** */ +:root { + --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,') +} + .md-typeset .admonition.pied-piper { border-color: rgb(43, 155, 70); } diff --git a/docs/_static/results.css b/docs/_static/results.css index 853c7429d..77ebc0b65 100644 --- a/docs/_static/results.css +++ b/docs/_static/results.css @@ -1,10 +1,5 @@ /* **************************** theme-results directive special ******************** */ -.md-typeset .code-block-caption+.notranslate pre, -.md-typeset .code-block-caption+.notranslate>.highlighttable { - margin-top: 0; -} - .result .results-prefix { margin-bottom: 1em; margin-top: 0.1rem; diff --git a/docs/admonitions.rst b/docs/admonitions.rst index b96c24a9a..95d425572 100644 --- a/docs/admonitions.rst +++ b/docs/admonitions.rst @@ -11,22 +11,26 @@ Most of the admonitions that the mkdocs-material theme supports were "borrowed" admonitions defined in the reStructuredText specifications. You may recognize them from usage in other sphinx-based themes. They are: -``note``, ``todo``, ``seealso`` +.. result:: ``note``, ``todo``, ``seealso`` + .. seealso:: This admonition is specific to Sphinx directives and not defined in the rST specifications as you can `seealso`. ``note`` and ``todo`` are admonitions defined by the rST specifications. -``tip``, ``hint``, ``important`` +.. result:: ``tip``, ``hint``, ``important`` + .. important:: It is **important** to correctly use admonitions. -``attention``, ``caution``, ``warning`` +.. result:: ``attention``, ``caution``, ``warning`` + .. warning:: This is a **warning**. -``danger``, ``error`` +.. result:: ``danger``, ``error`` + .. error:: You have made a grave **error**. @@ -45,80 +49,67 @@ shown inside the demonstrated admonition. styling to work. Otherwise, the admonition will look like a `note` (as that is the default fallback style). -``todo``, ``info`` +.. result:: ``todo``, ``info`` + .. admonition:: Info :class: info Thanks to the mkdocs-material theme, the ``todo`` class is also an alias of the ``info`` class when not using the ``.. todo::`` directive. - .. code-block:: rst +.. result:: ``abstract``, ``summary``, ``tldr`` - .. admonition:: Info - :class: info - -``abstract``, ``summary``, ``tldr`` .. admonition:: TL;DR :class: tldr - .. code-block:: rst + The ``:class: tldr`` part is important. - .. admonition:: TL;DR - :class: tldr +.. result:: ``success``, ``check``, ``done`` -``success``, ``check``, ``done`` - .. admonition:: Done + .. admonition:: Accomplished :class: done - .. code-block:: rst + This style is used for ``success``, ``check``, ``done`` CSS classes. + - .. admonition:: Done - :class: done +.. result:: ``question``, ``help``, ``faq`` -``question``, ``help``, ``faq`` .. admonition:: FAQ :class: faq - .. code-block:: rst + Helpful advice goes here. + - .. admonition:: FAQ - :class: faq +.. result:: ``failure``, ``fail``, ``missing`` -``failure``, ``fail``, ``missing`` - .. admonition:: Missing + .. admonition:: Something Missing :class: missing - .. code-block:: rst + We expected some loss of feature-coverage. - .. admonition:: Missing - :class: missing -``bug`` - .. admonition:: Bug +.. result:: ``bug`` + + .. admonition:: Known Bug :class: bug - .. code-block:: rst + Bug reported data/conclusion. + - .. admonition:: Bug - :class: bug +.. result:: ``example`` -``example`` - .. admonition:: Example + .. admonition:: Example Admonition :class: example - .. code-block:: rst + Example Body. - .. admonition:: Example - :class: example -``cite``, ``quote`` - .. admonition:: Quote - :class: quote +.. result:: ``cite``, ``quote`` - .. code-block:: rst + .. admonition:: Unknown Quote + :class: quote - .. admonition:: Quote - :class: quote + Somebody somewhere said something catchy. Collapsible dropdown ********************* @@ -136,27 +127,23 @@ The `sphinxcontrib-details-directive extension`_ should be added to conf.py's ex extensions = ["sphinx_immaterial", "sphinxcontrib.details.directive"] - If the ``:class:`` option is not supplied to the ``details`` directive then the admonition style falls back to a `note` admonition style. -.. details:: Open by default - :class: example - :open: +.. result:: - .. code-block:: rst + .. details:: Open by default + :class: example + :open: - .. details:: Open by default - :class: example - :open: + Use the ``:open:`` option as a flag to expand the admonition by default. -.. details:: Closed by default - :class: help +.. result:: - .. code-block:: rst + .. details:: Closed by default + :class: help - .. details:: Closed by default - :class: help + Without the ``:open:`` flag, the admonition is collapsed by default. Removing the title ****************** @@ -168,25 +155,20 @@ The admonition's title can be removed if the ``md-admonition`` directive is not any arguments. Because the ``md-admonition`` directive is an adaptation of the generic ``admonition`` directive, the ``class`` option is still respected. -.. md-admonition:: - :class: error - - This example uses the styling of the ``error`` admonition - .. code-block:: rst +.. result:: - .. md-admonition:: - :class: error + .. md-admonition:: + :class: error -.. md-admonition:: Using a title - :class: help + This example uses the styling of the ``error`` admonition - This example uses the styling of the ``help`` admonition +.. result:: - .. code-block:: rst + .. md-admonition:: Using a title + :class: help - .. md-admonition:: Using a title - :class: help + This example uses the styling of the ``help`` admonition .. hint:: You can use the ``md-admonition`` directive in other themes by adding the theme's module to your @@ -207,43 +189,26 @@ folder and add the new CSS to an additional style sheet. .. md-tab-item:: rST code - .. code-block:: rst + .. result:: Pied Piper Example + :output-prefix: .. admonition:: Pied Piper - :class: pied-piper + :class: pied-piper - Don't tell him you use spaces instead of tabs... + Don't tell him you use spaces instead of tabs... .. md-tab-item:: CSS code - .. code-block:: css + .. literalinclude:: _static/extra_css.css + :language: css :caption: docs/_static/extra_css.css - - :root { - --md-admonition-icon--pied-piper: url('data:image/svg+xml;charset=utf-8,') - } - .md-typeset .admonition.pied-piper { - border-color: rgb(43, 155, 70); - } - .md-typeset .pied-piper > .admonition-title { - background-color: rgba(43, 155, 70, 0.1); - border-color: rgb(43, 155, 70); - } - .md-typeset .pied-piper > .admonition-title::before { - background-color: rgb(43, 155, 70); - -webkit-mask-image: var(--md-admonition-icon--pied-piper); - mask-image: var(--md-admonition-icon--pied-piper); - } + :start-at: /* *************************** custom admonition style rules + :end-before: /* ********** .. md-tab-item:: conf.py code .. code-block:: python + :caption: docs/conf.py html_static_path = ["_static"] html_css_files = ["extra_css.css"] - - -.. admonition:: Pied Piper - :class: pied-piper - - Don't tell him you use spaces instead of tabs... diff --git a/docs/conf.py b/docs/conf.py index 212e58cc9..1b5005b67 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -35,6 +35,7 @@ "sphinx.ext.mathjax", "sphinx.ext.viewcode", "sphinxcontrib.details.directive", + "sphinx_immaterial.theme_result", ] intersphinx_mapping = { @@ -69,7 +70,8 @@ html_static_path = ["_static"] html_css_files = [ "extra_css.css", - "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css", + # "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css", + "results.css", ] # -- HTML theme settings ------------------------------------------------ @@ -131,12 +133,12 @@ { "version": "https://sphinx-immaterial.rtfd.io", "title": "ReadTheDocs", - "aliases": [] + "aliases": [], }, { "version": "https://jbms.github.io/sphinx-immaterial", "title": "Github Pages", - "aliases": [] + "aliases": [], }, ], "toc_title_is_page_title": True, diff --git a/docs/content_tabs.rst b/docs/content_tabs.rst index 85a2cbd66..469760741 100644 --- a/docs/content_tabs.rst +++ b/docs/content_tabs.rst @@ -42,7 +42,7 @@ the sphinx-immaterial theme provides its own directives to make use of content t This directive supports ``:class:`` and ``:name:`` options to use custom CSS classes and reference links (respectively). - .. code-block:: rst + .. result:: ``md-tab-set`` Example .. md-tab-set:: :class: custom-tab-set-style @@ -69,30 +69,6 @@ the sphinx-immaterial theme provides its own directives to make use of content t :start-at: /* ************************ custom-tab-set-style :end-before: /* *********************** custom-tab-item-style - .. md-tab-set:: - :class: custom-tab-set-style - :name: ref_this_tab_set - - .. md-tab-item:: Local Ref - - A reference to this tab set renders like so: - `tab set description `. - - This syntax can only be used on the same page as the tab set. - - .. md-tab-item:: Cross-page Ref - - To cross-reference this tab set from a different page, use - :ref:`tab set description ` - - Clearly, this also works on the same page as the tab set. - - .. md-tab-item:: Custom CSS - - .. literalinclude:: _static/extra_css.css - :language: css - :start-at: /* ************************ custom-tab-set-style - :end-before: /* *********************** custom-tab-item-style .. rst:directive:: md-tab-item @@ -108,7 +84,7 @@ the sphinx-immaterial theme provides its own directives to make use of content t Use the ``:class:`` option to optionally provide custom CSS classes to the tab's content (not the tab's label). - .. code-block:: rst + .. result:: ``md-tab-item`` Example .. md-tab-set:: @@ -124,19 +100,6 @@ the sphinx-immaterial theme provides its own directives to make use of content t :start-at: /* *********************** custom-tab-item-style :end-before: /* ************************* inline icon stuff - .. md-tab-set:: - - .. md-tab-item:: Customized content - :class: custom-tab-item-style - - This content could be styled differently from other page content. - - .. md-tab-item:: Custom CSS - - .. literalinclude:: _static/extra_css.css - :language: css - :start-at: /* *********************** custom-tab-item-style - :end-before: /* ************************* inline icon stuff Typical examples are seen in this documentations' `Custom admonitions `_ and diff --git a/docs/demo_api.rst b/docs/demo_api.rst index 7b05937dd..52801969c 100644 --- a/docs/demo_api.rst +++ b/docs/demo_api.rst @@ -7,56 +7,71 @@ sample API documentation and generated content :mod:`test_py_module` ===================== -.. automodule:: test_py_module.test - :members: - :private-members: - :special-members: +.. result:: autodoc example + .. automodule:: test_py_module.test + :members: + :private-members: + :special-members: C++ API ======= -.. cpp:type:: MyType +.. result:: - Some type + .. cpp:type:: MyType -.. cpp:function:: const MyType Foo(const MyType bar) + Some type - Some function type thing +.. result:: -.. cpp:class:: template std::array + .. cpp:function:: const MyType Foo(const MyType bar) - Some cpp class + Some function type thing -.. cpp:member:: float Sphinx::version +.. result:: - The description of Sphinx::version. + .. cpp:class:: template std::array -.. cpp:var:: int version + Some cpp class - The description of version. +.. result:: -.. cpp:type:: std::vector List + .. cpp:member:: float Sphinx::version - The description of List type. + The description of Sphinx::version. -.. cpp:enum:: MyEnum +.. result:: - An unscoped enum. + .. cpp:var:: int version - .. cpp:enumerator:: A + The description of version. -.. cpp:enum-class:: MyScopedEnum +.. result:: - A scoped enum. + .. cpp:type:: std::vector List - .. cpp:enumerator:: B + The description of List type. -.. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type::type +.. result:: - A scoped enum with non-default visibility, and with a specified underlying type. + .. cpp:enum:: MyEnum - .. cpp:enumerator:: B + An unscoped enum. + + .. cpp:enumerator:: A + + .. cpp:enum-class:: MyScopedEnum + + A scoped enum. + + .. cpp:enumerator:: B + + .. cpp:enum-struct:: protected MyScopedVisibilityEnum : std::underlying_type::type + + A scoped enum with non-default visibility, and with a specified underlying type. + + .. cpp:enumerator:: B JavaScript API @@ -66,34 +81,44 @@ JavaScript API .. js:module:: module_a.submodule -* Link to :js:class:`ModTopLevel` +.. result:: -.. js:class:: ModTopLevel + * Link to :js:class:`ModTopLevel` - * Link to :js:meth:`mod_child_1` - * Link to :js:meth:`ModTopLevel.mod_child_1` +.. result:: -.. js:method:: ModTopLevel.mod_child_1 + .. js:class:: ModTopLevel - * Link to :js:meth:`mod_child_2` + * Link to :js:meth:`mod_child_1` + * Link to :js:meth:`ModTopLevel.mod_child_1` -.. js:method:: ModTopLevel.mod_child_2 +.. result:: - * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1` + .. js:method:: ModTopLevel.mod_child_1 + + * Link to :js:meth:`mod_child_2` + + .. js:method:: ModTopLevel.mod_child_2 + + * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1` .. js:module:: module_b.submodule -* Link to :js:class:`ModTopLevel` +.. result:: + + * Link to :js:class:`ModTopLevel` -.. js:class:: ModNested +.. result:: - .. js:method:: nested_child_1 + .. js:class:: ModNested - * Link to :js:meth:`nested_child_2` + .. js:method:: nested_child_1 - .. js:method:: nested_child_2 + * Link to :js:meth:`nested_child_2` - * Link to :js:meth:`nested_child_1` + .. js:method:: nested_child_2 + + * Link to :js:meth:`nested_child_1` Generated Index @@ -110,18 +135,20 @@ However, some projects will manually do it, like so: This example comes from `django-payments module docs`_. -.. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl']) +.. result:: + + .. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl']) - This backend implements payments using a popular Polish gateway, `Dotpay.pl `_. + This backend implements payments using a popular Polish gateway, `Dotpay.pl `_. - Due to API limitations there is no support for transferring purchased items. + Due to API limitations there is no support for transferring purchased items. - :param seller_id: Seller ID assigned by Dotpay - :param pin: PIN assigned by Dotpay - :param channel: Default payment channel (consult reference guide) - :param lang: UI language - :param lock: Whether to disable channels other than the default selected above + :param seller_id: Seller ID assigned by Dotpay + :param pin: PIN assigned by Dotpay + :param channel: Default payment channel (consult reference guide) + :param lang: UI language + :param lock: Whether to disable channels other than the default selected above .. _cannot be generated from code: https://groups.google.com/forum/#!topic/sphinx-users/_qfsVT5Vxpw .. _django-payments module docs: http://django-payments.readthedocs.org/en/latest/modules.html#payments.authorizenet.AuthorizeNetProvide @@ -130,10 +157,12 @@ This example comes from `django-payments module docs`_. Data ==== -.. data:: Data_item_1 - Data_item_2 - Data_item_3 +.. result:: + + .. data:: Data_item_1 + Data_item_2 + Data_item_3 - Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis. + Lorem ipsum dolor sit amet, consectetur adipiscing elit. Fusce congue elit eu hendrerit mattis. -Some data link :data:`Data_item_1`. + Some data link :data:`Data_item_1`. diff --git a/docs/index.rst b/docs/index.rst index 1230d213b..f05587463 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -56,7 +56,7 @@ Update your ``conf.py`` with the required changes: There are a lot more ways to customize this theme. See :ref:`Customization` or ``theme.conf`` for more details. -.. admonition:: Settings used in this documentation +.. details:: Settings used in this documentation :class: example .. literalinclude:: ./conf.py diff --git a/docs/mermaid_diagrams.rst b/docs/mermaid_diagrams.rst index 59328cf65..f6c28732a 100644 --- a/docs/mermaid_diagrams.rst +++ b/docs/mermaid_diagrams.rst @@ -15,15 +15,15 @@ directive that exposes the underlying implementation in mkdocs-material theme. .. rst:directive:option:: class :type: string - + A space delimited list of qualified names that get used as the HTML element's ``class`` attribute. .. rst:directive:option:: name :type: string - + A qualified name that get used as the HTML element's ``id`` attribute. - + Use the `ref` role to reference the element by name. The `md-mermaid` directive's ``:class:`` and ``:name:`` options can be used @@ -34,16 +34,22 @@ directive that exposes the underlying implementation in mkdocs-material theme. .. md-admonition:: :class: missing - + While all `mermaid.js`_ features should work out-of-the-box, this theme will currently only - adjust the fonts and colors for `flowcharts`_, `sequence diagrams `, - `class diagrams `, `state diagrams `, and - `entity-relationship diagrams `. + adjust the fonts and colors for the following types of diagrams: + + .. result:: References linking directly to a diagram's ``:name:`` + + - `flowcharts`_ + - `sequence diagrams ` + - `class diagrams ` + - `state diagrams ` + - `entity-relationship diagrams ` Using flowcharts ---------------- -.. code-block:: rst +.. result:: .. md-mermaid:: :name: flowcharts @@ -55,20 +61,10 @@ Using flowcharts D --> B; B ---->|No| E[Yay!]; -.. md-mermaid:: - :name: flowcharts - - graph LR - A[Start] --> B{Error?}; - B -->|Yes| C[Hmm...]; - C --> D[Debug]; - D --> B; - B ---->|No| E[Yay!]; - Using sequence diagrams ----------------------- -.. code-block:: rst +.. result:: .. md-mermaid:: :name: sequence-diagrams @@ -83,23 +79,10 @@ Using sequence diagrams John->>Bob: How about you? Bob-->>John: Jolly good! -.. md-mermaid:: - :name: sequence-diagrams - - sequenceDiagram - Alice->>John: Hello John, how are you? - loop Healthcheck - John->>John: Fight against hypochondria - end - Note right of John: Rational thoughts! - John-->>Alice: Great! - John->>Bob: How about you? - Bob-->>John: Jolly good! - Using state diagrams -------------------- -.. code-block:: rst +.. result:: .. md-mermaid:: :name: state-diagrams @@ -116,26 +99,11 @@ Using state diagrams join_state --> State4 State4 --> [*] -.. md-mermaid:: - :name: state-diagrams - - stateDiagram-v2 - state fork_state <> - [*] --> fork_state - fork_state --> State2 - fork_state --> State3 - - state join_state <> - State2 --> join_state - State3 --> join_state - join_state --> State4 - State4 --> [*] Using class diagrams -------------------- - -.. code-block:: rst +.. result:: .. md-mermaid:: :name: class-diagrams @@ -164,44 +132,13 @@ Using class diagrams +int postalCode +String country -validate() - +outputAsLabel() + +outputAsLabel() } -.. md-mermaid:: - :name: class-diagrams - - classDiagram - Person <|-- Student - Person <|-- Professor - Person : +String name - Person : +String phoneNumber - Person : +String emailAddress - Person: +purchaseParkingPass() - Address "1" <-- "0..1" Person:lives at - class Student{ - +int studentNumber - +int averageMark - +isEligibleToEnrol() - +getSeminarsTaken() - } - class Professor{ - +int salary - } - class Address{ - +String street - +String city - +String state - +int postalCode - +String country - -validate() - +outputAsLabel() - } - Using entity-relationship diagrams ---------------------------------- - -.. code-block:: rst +.. result:: .. md-mermaid:: :name: entity-relationship-diagrams @@ -210,11 +147,3 @@ Using entity-relationship diagrams CUSTOMER ||--o{ ORDER : places ORDER ||--|{ LINE-ITEM : contains CUSTOMER }|..|{ DELIVERY-ADDRESS : uses - -.. md-mermaid:: - :name: entity-relationship-diagrams - - erDiagram - CUSTOMER ||--o{ ORDER : places - ORDER ||--|{ LINE-ITEM : contains - CUSTOMER }|..|{ DELIVERY-ADDRESS : uses From d0159335ad0e6c7f9f696938f2e534d973dd06e1 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:13:19 -0700 Subject: [PATCH 03/31] add task-list directive and keys role --- docs/conf.py | 6 ++ docs/index.rst | 2 + docs/keys.rst | 158 +++++++++++++++++++++++++++++++ docs/requirements.txt | 1 + docs/task_lists.rst | 161 ++++++++++++++++++++++++++++++++ sphinx_immaterial/__init__.py | 2 + sphinx_immaterial/kbd_keys.py | 112 ++++++++++++++++++++++ sphinx_immaterial/task_lists.py | 95 +++++++++++++++++++ 8 files changed, 537 insertions(+) create mode 100644 docs/keys.rst create mode 100644 docs/task_lists.rst create mode 100644 sphinx_immaterial/kbd_keys.py create mode 100644 sphinx_immaterial/task_lists.py diff --git a/docs/conf.py b/docs/conf.py index 1b5005b67..6bbc146cb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -36,6 +36,7 @@ "sphinx.ext.viewcode", "sphinxcontrib.details.directive", "sphinx_immaterial.theme_result", + "sphinx_immaterial.kbd_keys", ] intersphinx_mapping = { @@ -58,6 +59,11 @@ # This pattern also affects html_static_path and html_extra_path. exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +# -- sphinx_immaterial.keys extension options +# +# optional key_map for example purposes +keys_map = {"my-special-key": "Awesome Key", "git": ""} + # -- Options for HTML output ------------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for diff --git a/docs/index.rst b/docs/index.rst index f05587463..681b0ee10 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -71,6 +71,8 @@ or ``theme.conf`` for more details. admonitions content_tabs mermaid_diagrams + task_lists + keys .. toctree:: :caption: Examples and Uses diff --git a/docs/keys.rst b/docs/keys.rst new file mode 100644 index 000000000..71c2d849b --- /dev/null +++ b/docs/keys.rst @@ -0,0 +1,158 @@ +Keys extension +============== + +.. _pymdownx.keys: https://facelessuser.github.io/pymdown-extensions/extensions/keys/ + +This extension is meant to mimic the python markdown extension, `pymdownx.keys`_. + +It simply adds a role to invoke inline usage of keyboard keys with custom CSS provided by +the sphinx-immaterial theme. + +.. details:: CSS is not included with this extension + :class: success + + To add CSS to a theme that does not support this extension, try using: + + .. code-block:: CSS + + kbd[class^="key-"] { + background-color: var(--md-typeset-kbd-color); + border-radius: 0.1rem; + box-shadow: 0 0.1rem 0 0.05rem var(--md-typeset-kbd-border-color), 0 0.1rem 0 var(--md-typeset-kbd-border-color), 0 -0.1rem 0.2rem var(--md-typeset-kbd-accent-color) inset; + color: var(--md-default-fg-color); + display: inline-block; + font-size: 0.75em; + padding: 0 0.6666666667em; + vertical-align: text-top; + word-break: break-word; + font-feature-settings: "kern"; + font-family: var(--md-code-font-family); + } + + .keys span { + color: var(--md-default-fg-color--light); + padding: 0 0.2em; + } + +.. _pymdownx-keys-req: + +Markdown extension pre-requisite +-------------------------------- + +This pre-requisite does not mean Markdown support is enabled. However, this extension +does import the ``pymdownx.keymap_db`` module to use for the `keys_map` option's defaults. + +To use this extension, the pymdownx package needs to be installed. + +.. code-block:: shell + + python -m pip install pymdown-extensions + +And be sure to include the extension in your conf.py file. + +.. code-block:: python + + extensions = ["sphinx_immaterial.kbd_keys"] + +.. _keys_extension_role: + +Keys extension role +----------------------- + +.. rst:role:: keys + + The value of this role is interpreted as a keyboard key name. Each role invocation can + describe multiple keys pressed simultaneously using the `keys_separator`. + + .. result:: + + :keys:`ctrl+alt+tab` + + :keys:`caps-lock`, :keys:`left-cmd+shift+a`, :keys:`backspace` + +Keys extension configuration +------------------------------------- + +These variables can be used to control the :rst:role:`keys` role behavior from the Sphinx +project's conf.py file. + +.. confval:: keys_strict + + The containing span element can strictly follow HTML5 specifications by using the + ``kbd`` tag instead of a ``span`` tag. + + The sphinx-immaterial theme does not adhere to the HTML5 strictness, therefore this + `bool` option is disabled (`False`) by default. + +.. confval:: keys_class + + The class attribute `str` value used in the containing span element. Defaults to ``"keys"``. + + Only change this if needed for your theme. The sphinx-immaterial theme is configured to use + the default value. + +.. confval:: keys_separator + + The `str` value used as the delimiter between keys. Defaults to ``"+"``. + + Changing this also requires changing the text provided to the :rst:role:`keys` role. + +.. confval:: keys_map + + An additional `dict` where ``key: value`` pairs consist of: + + .. csv-table:: + :header: key, value + + aliased key-\ **name** inputs (preferably a CSS friendly name), displayed output `str` + + By default the english mappings are included from the `pymdownx package `. + + .. seealso:: + The tables in + `pymdownx.keys`_ docs in `Extending/Modifying Key-Map Index + `_. + + .. md-tab-set:: + + .. md-tab-item:: conf.py + + Define the key name and give it a `str` value to display. + + In our case, "Awesome Key" will be shown for ``:keys:`my-special-key```. + + .. literalinclude:: conf.py + :language: python + :start-at: # -- sphinx_immaterial.keys extension options + :end-before: # -- + + .. md-tab-item:: CSS code + + Remember to prepend ``key-`` to whatever the `keys_map` key was. In our case, + ``my-special-key`` turns into ``key-my-special-key``. + + .. literalinclude:: _static/extra_css.css + :language: css + :start-at: /* ************************* my-special-key style + :end-before: /* **************************** custom-task-list style rules + + + .. md-tab-item:: rST code + + Specify the key using a known name in the `keys_map` index. + + In our case, ``my-special-key`` to fetch the display text from `keys_map`. + + .. result:: + + :keys:`my-special-key` + :keys:`git` = :keys:`git+my-special-key` + + + Use of spaces in a key name will result in CSS class that has hyphens instead of + spaces in a lower case form of the given text. Therefore, entering + ``My Special Key`` ignores the `keys_map` but still uses the + ``key-my-special-key`` CSS class. + + .. result:: + + :keys:`My Special Key` + :keys:`Git` = :keys:`Git+My Special Key` diff --git a/docs/requirements.txt b/docs/requirements.txt index 4f1766b22..fa20fb5bf 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ # The sphinx docs theme to use sphinx_immaterial sphinxcontrib-details-directive +pymdown-extensions diff --git a/docs/task_lists.rst b/docs/task_lists.rst new file mode 100644 index 000000000..903967408 --- /dev/null +++ b/docs/task_lists.rst @@ -0,0 +1,161 @@ +Task Lists +============== + +This Sphinx extension mimics the HTML output of the ``pymdownx.tasklist`` Markdown +extension, which allows for the definition of task lists. With this extension and the +mkdocs-material theme's CSS, you can make list items prefixed with ``[ ]`` to render an unchecked +checkbox or ``[x]`` to render a checked checkbox. + +This extension can be optionally be used in other sphinx theme's that support checkboxes. + +.. code-block:: python + :caption: This is already done in sphinx-immaterial theme: + + extensions = ["sphinx_immaterial.task_lists"] + +.. details:: CSS not included with extension + :class: check + + The CSS for checkboxes is not included with this extension. Rather, the CSS is served from the + sphinx-immaterial theme (which is inherited from mkdocs-material theme). + + To use this extension with a theme that has no CSS support, try adding your own CSS: + + .. code-block:: css + + :root { + --md-task-list-icon: url('data:image/svg+xml;charset=utf-8,'); + --md-task-list-icon--checked: url('data:image/svg+xml;charset=utf-8,'); + } + + /* style for the unchecked checkboxes */ + .task-list-indicator::before { + -webkit-mask-image: var(--md-task-list-icon); + mask-image: var(--md-task-list-icon); + background-color: hsla(232deg, 75%, 90%, 0.12); + + content: ""; + height: 1.25em; + -webkit-mask-repeat: no-repeat; + mask-repeat: no-repeat; + -webkit-mask-size: contain; + mask-size: contain; + position: absolute; + top: .15em; + width: 1.25em; + } + + /* style for the checked checkboxes */ + .task-list-control > [type="checkbox"]:checked + .task-list-indicator::before { + -webkit-mask-image: var(--md-task-list-icon--checked); + mask-image: var(--md-task-list-icon--checked); + background-color: hsl(122deg, 84%, 45%); + } + +Config variables +---------------- + +.. confval:: custom_checkbox + + A global conf.py `bool` variable to enable custom CSS for all checkboxes shown. Default is `False`. + +.. confval:: clickable_checkbox + + A global conf.py `bool` variable to enable user interaction with the checkboxes shown. Default is `False`. + + .. note:: + If this option is used, then any user changes will not be saved. + +``task-list`` Directive +----------------------- + +.. rst:directive:: task-list + + This directive traverses the immediate list's items and adds a checkbox according to + GitHub Flavored MarkDown. + + + .. rst:directive:option:: class + :type: string + + A space delimited list of qualified names that get used as the HTMl element's + ``class`` attribute. + + The ``class`` option is only applied to the containing ``div`` element. + + .. md-tab-set:: + + .. md-tab-item:: rST code + + .. result:: Custom icons scoped to immediate list only (not child lists) + + .. task-list:: + :class: custom-task-list-style + :custom: + + + [ ] Custom unchecked checkbox + + [x] Custom checked checkbox + + .. task-list:: + :custom: + + * [ ] A goal for a task. + * [x] A fulfilled goal. + + .. md-tab-item:: CSS Hint + + .. literalinclude:: _static/extra_css.css + :language: css + :start-at: /* **************************** custom-task-list style rules + :end-before: /* *************************** custom admonition style rules + + .. rst:directive:option:: name + :type: string + + A qualified name that get used as the HTML element's ``name`` attribute. + + The ``name`` option is only applied to the containing ``div`` element. + Use the `ref` role to reference the element by name. + + .. rst:directive:option:: custom + :type: flag + + Allow custom styled checkboxes. Default is `False` unless `custom_checkbox` is enabled. + + .. rst:directive:option:: clickable + :type: flag + + Allow user interaction with checkboxes. Default is `False` unless `clickable_checkbox` is enabled. + + .. note:: + If this option is used, then any user changes will not be saved. + +Task List Example +----------------- + +The following `task-list` example demonstrates nested `task-list`. +Notice that indentation is important with reStructuredText lists. + +.. result:: A feature spanning ``task-list`` example + + .. task-list:: + :name: task_list_example + :custom: + + 1. [x] Task A + 2. [ ] Task B + + .. task-list:: + :clickable: + + * [x] Task B1 + * [x] Task B2 + * [] Task B3 + + A rogue paragraph with a reference to + the `parent task_list `. + + - A list item without a checkbox. + - [ ] Another bullet point. + + 3. [ ] Task C diff --git a/sphinx_immaterial/__init__.py b/sphinx_immaterial/__init__.py index 055b17ab3..23366bee1 100644 --- a/sphinx_immaterial/__init__.py +++ b/sphinx_immaterial/__init__.py @@ -291,6 +291,8 @@ def setup(app): app.setup_extension("sphinx_immaterial.md_admonition") app.setup_extension("sphinx_immaterial.content_tabs") app.setup_extension("sphinx_immaterial.mermaid_diagrams") + app.setup_extension("sphinx_immaterial.task_lists") + # patch the details directive's run method monkey_patch_details_run() diff --git a/sphinx_immaterial/kbd_keys.py b/sphinx_immaterial/kbd_keys.py new file mode 100644 index 000000000..68611f0fc --- /dev/null +++ b/sphinx_immaterial/kbd_keys.py @@ -0,0 +1,112 @@ +from typing import List, Tuple +from docutils import nodes +from sphinx.application import Sphinx +from sphinx.config import Config +from sphinx.writers.html import HTMLTranslator +from sphinx.util.logging import getLogger + +LOGGER = getLogger(__name__) + +try: + import pymdownx.keymap_db as keys_db +except ImportError: + LOGGER.info( + "Could not import `keymap_db` module from `pymdownx` package.\n " + "Please ensure `pymdown-extensions` is installed.\n " + "The `:keys:` role has no default key map." + ) + keys_db = None + + +class spanNode(nodes.container): + pass + + +def visit_span(self: HTMLTranslator, node: spanNode): + self.body.append("" + node["text"]) + else: + self.body.append(">") + + +def depart_span(self: HTMLTranslator, node: spanNode): + self.body.append("") + + +class kbdNode(nodes.container): + pass + + +def visit_kbd(self, node): + self.body.append( + '' + node["text"]) + else: + self.body.append('">') + + +def depart_kbd(self, node): + self.body.append("") + + +def keys_role( + role, rawtext, text, lineno, inliner, options={}, content=[] +) -> Tuple[List[nodes.Node], List[str]]: + keys = text.split(KEYS_OPTS["keys_sep"]) + keys_div = spanNode("", classes=[KEYS_OPTS["keys_class"]]) + if KEYS_OPTS["keys_strict"]: + keys_div = kbdNode("", classes=[KEYS_OPTS["keys_class"]]) + keys_out = [] + + def map_filter(key: str) -> Tuple[str, str]: + display = key.title() + cls = key.replace("_", "-").replace(" ", "-").lower() + if key in KEYS_OPTS["keys_map"].keys(): + display = KEYS_OPTS["keys_map"][key] + if keys_db is not None: + if key in keys_db.aliases.keys(): + display = keys_db.keymap[keys_db.aliases[key]] + cls = keys_db.aliases[key] + return (cls, display) + + for i, key in enumerate(keys): + key_cls, key_display = map_filter(key.strip().lower()) + keys_key = kbdNode("", classes=["key-" + key_cls]) + keys_key["text"] = key_display + keys_out.append(keys_key) + if i + 1 != len(keys): + keys_sep = spanNode("", classes=[]) + keys_sep["text"] = KEYS_OPTS["keys_sep"] + keys_out.append(keys_sep) + keys_div += keys_out + return [keys_div], [] + + +KEYS_OPTS = {"keys_map": ({} if keys_db is None else keys_db.keymap.copy())} + + +def _config_inited(app: Sphinx, config: Config) -> None: + """Set defaults for `key` role options based on conf.py vars.""" + KEYS_OPTS["keys_class"] = app.config["keys_class"] + KEYS_OPTS["keys_sep"] = app.config["keys_separator"] + KEYS_OPTS["keys_strict"] = app.config["keys_strict"] + if app.config["keys_map"].keys(): + KEYS_OPTS["keys_map"].update(**app.config["keys_map"]) + + +def setup(app: Sphinx): + app.add_config_value("keys_class", "keys", rebuild=True, types=str) + app.add_config_value("keys_strict", False, rebuild=True, types=bool) + app.add_config_value("keys_separator", "+", rebuild=True, types=str) + app.add_config_value("keys_map", {}, rebuild=True, types=dict) + app.add_role("keys", keys_role) + app.connect("config-inited", _config_inited) + app.add_node(spanNode, html=(visit_span, depart_span)) + app.add_node(kbdNode, html=(visit_kbd, depart_kbd)) diff --git a/sphinx_immaterial/task_lists.py b/sphinx_immaterial/task_lists.py new file mode 100644 index 000000000..c4e46737d --- /dev/null +++ b/sphinx_immaterial/task_lists.py @@ -0,0 +1,95 @@ +"""A custom directive that allows using checkboxes for lists""" +from typing import List +from docutils import nodes +from docutils.parsers.rst import directives +from sphinx.util.docutils import SphinxDirective +from sphinx.application import Sphinx +from sphinx.writers.html import HTMLTranslator + + +def visit_checkbox_label(self: HTMLTranslator, node: nodes.Node): + attributes = {} + if node["custom"]: + attributes = {"class": "task-list-control"} + self.body.append(self.starttag(node, "label", **attributes)) + self.body.append('") + if node["custom"]: + self.body.append('') + + +def depart_checkbox_label(self: HTMLTranslator, node: nodes.Node): + self.body.append("") + + +class checkboxLabel(nodes.container): + pass + + +class TaskListDirective(SphinxDirective): + """a special directive""" + + has_content = True + optional_arguments = 4 + option_spec = { + "name": directives.unchanged, + "class": directives.class_option, + "custom": directives.flag, + "clickable": directives.flag, + } + + def run(self) -> List[nodes.Node]: + """Run the directive.""" + self.assert_has_content() + task_list = nodes.container( + "", is_div=True, classes=self.options.get("class", []) + ) + if self.options.get("name", ""): + self.add_name(task_list) + clickable = "clickable" in self.options or self.config["clickable_checkbox"] + custom = "custom" in self.options or self.config["custom_checkbox"] + self.state.nested_parse(self.content, self.content_offset, task_list) + self.set_source_info(task_list) + + def first_matching(obj, cls_t): + return obj.first_child_matching_class(cls_t) + + for child in task_list.children: + if isinstance(child, nodes.list_item): + child["classes"] = ["task-list"] + + for li_ in child.children: + if isinstance(li_, nodes.list_item): + if li_.astext().startswith("["): + li_["classes"] = ["task-list-item"] + checked = li_.astext().lower().startswith("[x]") + first_para = first_matching(li_, nodes.paragraph) + if first_para is not None: + first_text = first_matching(li_[first_para], nodes.Text) + li_[first_para][first_text] = li_[first_para][ + first_text + ].lstrip("[x] ") + li_[first_para][first_text] = li_[first_para][ + first_text + ].lstrip("[ ] ") + checkbox = checkboxLabel( + "", + custom=custom, + disabled=not clickable, + checked=checked, + ) + li_.insert(0, checkbox) + + return [task_list] + + +def setup(app: Sphinx): + """Setup the extension.""" + app.add_directive("task-list", TaskListDirective) + app.add_node(checkboxLabel, html=(visit_checkbox_label, depart_checkbox_label)) + app.add_config_value("custom_checkbox", False, rebuild="html", types=bool) + app.add_config_value("clickable_checkbox", False, rebuild="html", types=bool) From 186e5cad66d045a73f008c7db835fb8f83e195d3 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:13:57 -0700 Subject: [PATCH 04/31] add experimental button idea --- docs/buttons.rst | 31 +++++++ docs/index.rst | 1 + sphinx_immaterial/button.py | 159 ++++++++++++++++++++++++++++++++++++ 3 files changed, 191 insertions(+) create mode 100644 docs/buttons.rst create mode 100644 sphinx_immaterial/button.py diff --git a/docs/buttons.rst b/docs/buttons.rst new file mode 100644 index 000000000..ae3dcf3ca --- /dev/null +++ b/docs/buttons.rst @@ -0,0 +1,31 @@ + +Buttons +=========== + +Directives +----------- + +.. result:: Some examples of the button directives + :output-prefix: + + .. md-button-primary:: `keys_extension_role` + :class: lcars-button + + Clickable buttons are next! + + .. md-button:: http://www.example.com + :class: lcars-button + + some text + +Roles +----------- + +.. result:: Some examples of the button roles. + :output-prefix: Which produces something like this: + + :md-button:`https://www.example.com` + + :ref:`keys ext role ` + + :md-button-primary:`keys ext role ` diff --git a/docs/index.rst b/docs/index.rst index 681b0ee10..90021d084 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -73,6 +73,7 @@ or ``theme.conf`` for more details. mermaid_diagrams task_lists keys + buttons .. toctree:: :caption: Examples and Uses diff --git a/sphinx_immaterial/button.py b/sphinx_immaterial/button.py new file mode 100644 index 000000000..145e49bcf --- /dev/null +++ b/sphinx_immaterial/button.py @@ -0,0 +1,159 @@ +"""A simple directive that creates a HTML ```` element.""" + +from typing import List, Any, Tuple +from docutils.parsers.rst import directives +from docutils import nodes +from sphinx.application import Sphinx +from sphinx.util.docutils import SphinxDirective +from sphinx import addnodes +from sphinx.roles import AnyXRefRole +from sphinx.writers.html import HTMLTranslator +from sphinx.util.logging import getLogger +from docutils.parsers.rst import states + +LOGGER = getLogger(__name__) + + +class a_tag_node(nodes.container): + pass + + +def visit_a_tag(self: HTMLTranslator, node: a_tag_node): + attributes = {"class": " ".join(node["classes"])} + if "href" in node: + attributes["href"] = node["href"] + if "reftarget" in node: + attributes["href"] = node["reftarget"] + self.body.append(self.starttag(node, "a", **attributes)) + + +def depart_a_tag(self: HTMLTranslator, node: a_tag_node): + self.body.append("") + + +class MaterialButtonRole(AnyXRefRole): + def result_nodes( + self, + document: nodes.document, + env: "BuildEnvironment", + node: nodes.Element, + is_ref: bool, + ) -> Tuple[List[nodes.Node], List[str]]: + node["classes"] += ["md-button"] + return super().result_nodes(document, env, node, is_ref) + + +class MaterialButtonPrimaryRole(AnyXRefRole): + def result_nodes( + self, + document: nodes.document, + env: "BuildEnvironment", + node: nodes.Element, + is_ref: bool, + ) -> Tuple[List[nodes.Node], List[str]]: + node["classes"] += ["md-button", "md-button--primary"] + return super().result_nodes(document, env, node, is_ref) + + +class BasicButton(SphinxDirective): + + has_content = True + required_arguments = 1 + option_spec = { + "name": directives.unchanged, + "class": directives.class_option, + "is-md": directives.flag, + "is-md-primary": directives.flag, + } + + def run(self) -> List[nodes.Node]: + """Run the directive.""" + default_cls = [] + if self.options is not None: + default_cls = self.options.get("class", []) + if "is-md" in self.options: + default_cls.append("md-button") + if "is-md-primary" in self.options: + default_cls.append("md-button--primary") + a_tag = a_tag_node("", classes=default_cls, href=self.arguments[0]) + if self.options.get("name", ""): + self.add_name(a_tag) + textnodes, _ = self.state.inline_text(self.arguments[0], self.lineno) + if not self.content: + a_tag += textnodes + else: + a_tag["alt"] = textnodes + for line in self.content: + content, _ = self.state.inline_text(line, self.content_offset) + a_tag += content + return [a_tag] + + +class MaterialButton(BasicButton): + def __init__( + self, + name: str, + arguments: list[Any], + options: dict[str, Any], + content: list[str], + lineno: int, + content_offset: int, + block_text: str, + state: states.RSTState, + state_machine: states.RSTStateMachine, + ) -> None: + if options is not None: + options["is-md"] = True + else: + options = {"is-md": True} + super().__init__( + name, + arguments, + options, + content, + lineno, + content_offset, + block_text, + state, + state_machine, + ) + + +class MaterialButtonPrimary(MaterialButton): + def __init__( + self, + name: str, + arguments: list[Any], + options: dict[str, Any], + content: list[str], + lineno: int, + content_offset: int, + block_text: str, + state: states.RSTState, + state_machine: states.RSTStateMachine, + ) -> None: + if options is not None: + options["is-md-primary"] = True + else: + options = {"is-md-primary": True} + super().__init__( + name, + arguments, + options, + content, + lineno, + content_offset, + block_text, + state, + state_machine, + ) + + +def setup(app: Sphinx): + """Setup the extension.""" + app.add_directive("button", BasicButton) + app.add_directive("md-button", MaterialButton) + app.add_directive("md-button-primary", MaterialButtonPrimary) + app.add_node(a_tag_node, html=(visit_a_tag, depart_a_tag)) + app.add_role("md-button", MaterialButtonRole()) + app.add_role("md-button-primary", MaterialButtonPrimaryRole()) From 8e60344f16ab4e5e7ce9c2a92226ab23ea8adb7d Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:15:34 -0700 Subject: [PATCH 05/31] add in new demo CSS --- docs/_static/extra_css.css | 40 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index ce1c49581..c88cf09fe 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -18,6 +18,46 @@ --md-icon__fa-bitbucket: url('data:image/svg+xml;charset=utf-8,'); } +.md-typeset a.lcars-button { + border-radius: 36px; +} + +/* ************************* my-special-key style ************************************* */ + +.md-typeset kbd.key-my-special-key, +.md-typeset kbd.key-git { + color: var(--md-primary-fg-color); + background: var(--md-accent-bg-color); +} + +.md-typeset kbd.key-git::before { + content: "██"; + --webmask-image: var(--md-icon__fa-git); + mask-image: var(--md-icon__fa-git); + mask-repeat: no-repeat; +} + +.md-typeset kbd.key-my-special-key:hover, +.md-typeset kbd.key-git:hover { + color: var(--md-accent-fg-color); +} + +/* **************************** custom-task-list style rules *************************** */ + +/* style for the unchecked checkboxes */ +.custom-task-list-style>ul>.task-list-item>.task-list-control>.task-list-indicator::before { + -webkit-mask-image: var(--md-admonition-icon--failure); + mask-image: var(--md-admonition-icon--failure); + background-color: hsl(0, 72%, 55%); +} + +/* style for the checked checkboxes */ +.custom-task-list-style>ul>.task-list-item>.task-list-control>[type="checkbox"]:checked+.task-list-indicator::before { + -webkit-mask-image: var(--md-admonition-icon--success); + mask-image: var(--md-admonition-icon--success); + background-color: hsl(122, 84%, 45%); +} + /* *************************** custom admonition style rules *************************** */ :root { From a150c2b7bfe345d2baad6d09a7380c3b620d144f Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:28:00 -0700 Subject: [PATCH 06/31] pleasing pylint --- sphinx_immaterial/button.py | 6 ++---- sphinx_immaterial/kbd_keys.py | 2 +- 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/sphinx_immaterial/button.py b/sphinx_immaterial/button.py index 145e49bcf..96d9fdfbb 100644 --- a/sphinx_immaterial/button.py +++ b/sphinx_immaterial/button.py @@ -1,15 +1,13 @@ """A simple directive that creates a HTML ```` element.""" from typing import List, Any, Tuple -from docutils.parsers.rst import directives +from docutils.parsers.rst import directives, states from docutils import nodes from sphinx.application import Sphinx from sphinx.util.docutils import SphinxDirective -from sphinx import addnodes from sphinx.roles import AnyXRefRole from sphinx.writers.html import HTMLTranslator from sphinx.util.logging import getLogger -from docutils.parsers.rst import states LOGGER = getLogger(__name__) @@ -88,7 +86,7 @@ def run(self) -> List[nodes.Node]: a_tag += content return [a_tag] - +# pylint: disable=too-many-arguments class MaterialButton(BasicButton): def __init__( self, diff --git a/sphinx_immaterial/kbd_keys.py b/sphinx_immaterial/kbd_keys.py index 68611f0fc..b9b31547a 100644 --- a/sphinx_immaterial/kbd_keys.py +++ b/sphinx_immaterial/kbd_keys.py @@ -71,7 +71,7 @@ def map_filter(key: str) -> Tuple[str, str]: if key in KEYS_OPTS["keys_map"].keys(): display = KEYS_OPTS["keys_map"][key] if keys_db is not None: - if key in keys_db.aliases.keys(): + if key in keys_db.aliases: display = keys_db.keymap[keys_db.aliases[key]] cls = keys_db.aliases[key] return (cls, display) From f9697ce9deb83eafd0f80ac45c8c2439be401082 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 31 Mar 2022 18:29:46 -0700 Subject: [PATCH 07/31] ran black on button.py --- sphinx_immaterial/button.py | 1 + 1 file changed, 1 insertion(+) diff --git a/sphinx_immaterial/button.py b/sphinx_immaterial/button.py index 96d9fdfbb..983efab27 100644 --- a/sphinx_immaterial/button.py +++ b/sphinx_immaterial/button.py @@ -86,6 +86,7 @@ def run(self) -> List[nodes.Node]: a_tag += content return [a_tag] + # pylint: disable=too-many-arguments class MaterialButton(BasicButton): def __init__( From e89e923bfe4c0919181fe28ddd4b1f3b7cd84e98 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Fri, 1 Apr 2022 19:50:33 -0700 Subject: [PATCH 08/31] partial solution to content tabs in #56 --- sphinx_immaterial/content_tabs.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/sphinx_immaterial/content_tabs.py b/sphinx_immaterial/content_tabs.py index 15a809ad3..f941b2544 100644 --- a/sphinx_immaterial/content_tabs.py +++ b/sphinx_immaterial/content_tabs.py @@ -91,9 +91,7 @@ def run(self) -> List[nodes.Node]: # add tab label textnodes, _ = self.state.inline_text(self.arguments[0], self.lineno) - tab_label = nodes.rubric( - self.arguments[0], *textnodes, classes=["tabbed-label"] - ) + tab_label = nodes.rubric("", "", *textnodes, classes=["tabbed-label"]) self.add_name(tab_label) tab_item += tab_label @@ -152,6 +150,7 @@ def visit_tab_set(self: HTMLTranslator, node: content_tab_set): # create: label_node = content_tab_label( + "", "", *tab_label.children, input_id=tab_item_identity, From c699f76a9de29af2f2931d3eb91859d945ef8ede Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 5 Apr 2022 16:27:12 -0700 Subject: [PATCH 09/31] improve api doc signatures and code block captions --- docs/_static/extra_css.css | 23 +++++++++ docs/_static/results.css | 11 ----- docs/admonitions.rst | 10 +--- docs/conf.py | 2 +- docs/demo_api.rst | 21 ++++++-- docs/mermaid_diagrams.rst | 3 +- docs/test_py_module/test.py | 5 ++ sphinx_immaterial/__init__.py | 2 - sphinx_immaterial/apidoc_formatting.py | 43 +++++++++++++++++ sphinx_immaterial/object_toc.py | 2 +- sphinx_immaterial/patch_literal_blocks.py | 58 ----------------------- src/assets/stylesheets/main/_api.scss | 34 +++++++++---- 12 files changed, 119 insertions(+), 95 deletions(-) delete mode 100644 docs/_static/results.css delete mode 100644 sphinx_immaterial/patch_literal_blocks.py diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index c88cf09fe..f106d67fa 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -18,10 +18,33 @@ --md-icon__fa-bitbucket: url('data:image/svg+xml;charset=utf-8,'); } +/* **************************** test buttons' LCARS style ************************** */ + .md-typeset a.lcars-button { border-radius: 36px; } +/* **************************** theme-results directive special ******************** */ + +.result .results-prefix { + margin-bottom: 1em; + margin-top: 0.1rem; + background-color: var(--md-code-bg-color); + overflow: visible; + border-bottom-left-radius: 0.5rem; + border-bottom-right-radius: 0.5rem; + padding: 0 0.5rem; +} + +.md-typeset :is(.highlight, .highlighttable, .literal-block-wrapper) + .result { + border: .05rem solid var(--md-code-bg-color); + border-bottom-left-radius: .1rem; + border-bottom-right-radius: .1rem; + border-top-width: .1rem; + margin-top: -1.125em; + overflow: visible; + padding: 0 1em; +} /* ************************* my-special-key style ************************************* */ .md-typeset kbd.key-my-special-key, diff --git a/docs/_static/results.css b/docs/_static/results.css deleted file mode 100644 index 77ebc0b65..000000000 --- a/docs/_static/results.css +++ /dev/null @@ -1,11 +0,0 @@ -/* **************************** theme-results directive special ******************** */ - -.result .results-prefix { - margin-bottom: 1em; - margin-top: 0.1rem; - background-color: var(--md-code-bg-color); - overflow: visible; - border-bottom-left-radius: 0.5rem; - border-bottom-right-radius: 0.5rem; - padding: 0 0.5rem; -} diff --git a/docs/admonitions.rst b/docs/admonitions.rst index 95d425572..bc228a317 100644 --- a/docs/admonitions.rst +++ b/docs/admonitions.rst @@ -42,7 +42,7 @@ These admonitions can still be used, but the syntax is a little different becaus on the generic admonition defined in the reStructuredText specifications. To use the following admonitions' styles from the mkdocs-material theme, the rST syntax is -shown inside the demonstrated admonition. +shown to demonstrate using the ``:class:`` option of generic admonitions. .. important:: The ``:class:`` options below (in the rST code blocks) must use lower case letters for the @@ -55,7 +55,7 @@ shown inside the demonstrated admonition. :class: info Thanks to the mkdocs-material theme, the ``todo`` class is also an alias of the - ``info`` class when not using the ``.. todo::`` directive. + ``info`` class when not using the `.. todo:: ` directive. .. result:: ``abstract``, ``summary``, ``tldr`` @@ -71,7 +71,6 @@ shown inside the demonstrated admonition. This style is used for ``success``, ``check``, ``done`` CSS classes. - .. result:: ``question``, ``help``, ``faq`` .. admonition:: FAQ @@ -79,7 +78,6 @@ shown inside the demonstrated admonition. Helpful advice goes here. - .. result:: ``failure``, ``fail``, ``missing`` .. admonition:: Something Missing @@ -87,7 +85,6 @@ shown inside the demonstrated admonition. We expected some loss of feature-coverage. - .. result:: ``bug`` .. admonition:: Known Bug @@ -95,7 +92,6 @@ shown inside the demonstrated admonition. Bug reported data/conclusion. - .. result:: ``example`` .. admonition:: Example Admonition @@ -103,7 +99,6 @@ shown inside the demonstrated admonition. Example Body. - .. result:: ``cite``, ``quote`` .. admonition:: Unknown Quote @@ -155,7 +150,6 @@ The admonition's title can be removed if the ``md-admonition`` directive is not any arguments. Because the ``md-admonition`` directive is an adaptation of the generic ``admonition`` directive, the ``class`` option is still respected. - .. result:: .. md-admonition:: diff --git a/docs/conf.py b/docs/conf.py index 6bbc146cb..9b5cec569 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,6 +37,7 @@ "sphinxcontrib.details.directive", "sphinx_immaterial.theme_result", "sphinx_immaterial.kbd_keys", + "sphinx_immaterial.button", ] intersphinx_mapping = { @@ -77,7 +78,6 @@ html_css_files = [ "extra_css.css", # "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css", - "results.css", ] # -- HTML theme settings ------------------------------------------------ diff --git a/docs/demo_api.rst b/docs/demo_api.rst index 52801969c..78e37cbd5 100644 --- a/docs/demo_api.rst +++ b/docs/demo_api.rst @@ -25,13 +25,15 @@ C++ API .. result:: - .. cpp:function:: const MyType Foo(const MyType bar) + .. c:macro:: DEFAULT_LENGTH + + .. cpp:function:: const MyType Foo(const MyType bar, uint8_t* arr, unsigned int len = DEFAULT_LENGTH, bool baz= false) Some function type thing .. result:: - .. cpp:class:: template std::array + .. cpp:class:: template std::array Some cpp class @@ -39,7 +41,7 @@ C++ API .. cpp:member:: float Sphinx::version - The description of Sphinx::version. + The description of `Sphinx::version`. .. result:: @@ -102,12 +104,12 @@ JavaScript API * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1` -.. js:module:: module_b.submodule - .. result:: * Link to :js:class:`ModTopLevel` +.. js:module:: module_b.submodule + .. result:: .. js:class:: ModNested @@ -120,6 +122,15 @@ JavaScript API * Link to :js:meth:`nested_child_1` + .. js:method:: getJSON(href, callback, priority[, err_back, flags]) + + :param string href: An URI to the location of the resource. + :param callback: Gets called with the object. + :param err_back: + Gets called in case the request fails. And a lot of other + text so we need multiple lines. + :throws SomeError: For whatever reason in that case. + :returns: Something. Generated Index =============== diff --git a/docs/mermaid_diagrams.rst b/docs/mermaid_diagrams.rst index f6c28732a..28fd5aa24 100644 --- a/docs/mermaid_diagrams.rst +++ b/docs/mermaid_diagrams.rst @@ -4,7 +4,8 @@ Mermaid diagrams ================ .. note:: - Use of this feature has no affect or affiliation with sphinx's graphviz implementation. + Use of this feature has no affect or affiliation with sphinx's + :py:mod:`graphviz ` implementation. The mkdocs-material theme is equipped to make use of diagrams generated (during page load time) with `mermaid.js`_. Although, its implementation relies on a markdown extension that does not get diff --git a/docs/test_py_module/test.py b/docs/test_py_module/test.py index f47b9840c..3c8d656e2 100644 --- a/docs/test_py_module/test.py +++ b/docs/test_py_module/test.py @@ -1,5 +1,6 @@ # -*- coding: utf-8 -*- """Test Module for sphinx_rtd_theme.""" +from typing import Union class Foo: @@ -111,3 +112,7 @@ def another_function(self, a, b, **kwargs): This is deprecated since 3.0 """ return sum(kwargs.values()) / len(kwargs), a + b + +def func(long: int, param: str, args: None, flags: bool, lists: Union[list, tuple]): + """A function with many parameters.""" + return None diff --git a/sphinx_immaterial/__init__.py b/sphinx_immaterial/__init__.py index 23366bee1..b7866c8f8 100644 --- a/sphinx_immaterial/__init__.py +++ b/sphinx_immaterial/__init__.py @@ -20,7 +20,6 @@ from . import object_toc from . import postprocess_html from . import search_adapt -from . import patch_literal_blocks from .details_patch import monkey_patch_details_run logger = sphinx.util.logging.getLogger(__name__) @@ -277,7 +276,6 @@ def setup(app): app.setup_extension(inlinesyntaxhighlight.__name__) app.setup_extension(object_toc.__name__) app.setup_extension(search_adapt.__name__) - app.setup_extension(patch_literal_blocks.__name__) app.connect("html-page-context", html_page_context) app.connect("builder-inited", _builder_inited) app.add_config_value( diff --git a/sphinx_immaterial/apidoc_formatting.py b/sphinx_immaterial/apidoc_formatting.py index 9747133ec..362678041 100644 --- a/sphinx_immaterial/apidoc_formatting.py +++ b/sphinx_immaterial/apidoc_formatting.py @@ -134,6 +134,7 @@ def visit_desc(self, node: sphinx.addnodes.desc) -> None: # Augment the list of classes with `objdesc` to make it easier to # style these without resorting to hacks. + # add highlight to invoke syntax highlighting in CSS node["classes"].append("objdesc") super().visit_desc(node) @@ -147,6 +148,7 @@ def depart_desc_type(self, node: sphinx.addnodes.desc_type) -> None: def visit_desc_signature(self, node: sphinx.addnodes.desc_signature) -> None: node_text = node.astext() + node["classes"].append("highlight") if len(node_text) > SIGNATURE_WRAP_LENGTH: node["classes"].append("sig-wrap") super().visit_desc_signature(node) @@ -174,6 +176,47 @@ def depart_term(self, node: docutils.nodes.Element) -> None: self.add_permalink_ref(node, _("Permalink to this definition")) super().depart_term(node) + def visit_caption(self, node: docutils.nodes.Element) -> None: + attributes = {"class": "caption-text"} + if isinstance(node.parent, docutils.nodes.container) and node.parent.get( + "literal_block" + ): + # add highlight class to caption's div container. + # This is needed to trigger mkdocs-material CSS rule `.highlight .filename` + self.body.append('
') + # append a CSS class to trigger mkdocs-material theme's caption CSS style + attributes["class"] += " filename" + else: + super().visit_caption(node) + self.add_fignumber(node.parent) + self.body.append(self.starttag(node, "span", **attributes)) + + def depart_caption(self, node: docutils.nodes.Element) -> None: + if not isinstance( + node.parent, docutils.nodes.container + ) and not node.parent.get("literal_block"): + # only append ending tag if parent is not a literal-block. + # Because all elements in the caption should be within a span element + self.body.append("") + + # append permalink if available + if isinstance(node.parent, docutils.nodes.container) and node.parent.get( + "literal_block" + ): + self.add_permalink_ref(node.parent, _("Permalink to this code")) + self.body.append("") # done; add closing tag + elif isinstance(node.parent, docutils.nodes.figure): + self.add_permalink_ref(node.parent, _("Permalink to this image")) + elif node.parent.get("toctree"): + self.add_permalink_ref(node.parent.parent, _("Permalink to this toctree")) + + if isinstance(node.parent, docutils.nodes.container) and node.parent.get( + "literal_block" + ): + self.body.append("
\n") + else: + super().depart_caption(node) + def _monkey_patch_python_get_signature_prefix( directive_cls: Type[sphinx.domains.python.PyObject], diff --git a/sphinx_immaterial/object_toc.py b/sphinx_immaterial/object_toc.py index 936971f57..3de92dc63 100644 --- a/sphinx_immaterial/object_toc.py +++ b/sphinx_immaterial/object_toc.py @@ -15,7 +15,7 @@ def _monkey_patch_toc_tree_process_doc(app: sphinx.application.Sphinx): """ TocTreeCollector = sphinx.environment.collectors.toctree.TocTreeCollector - # Apply the monkey pach + # Apply the monkey patch orig_process_doc = TocTreeCollector.process_doc def _make_section_from_desc( diff --git a/sphinx_immaterial/patch_literal_blocks.py b/sphinx_immaterial/patch_literal_blocks.py deleted file mode 100644 index dba4e2f81..000000000 --- a/sphinx_immaterial/patch_literal_blocks.py +++ /dev/null @@ -1,58 +0,0 @@ -"""A monkey patch to conform code-blocks to superfences' output.""" -from docutils import nodes -from sphinx.transforms.post_transforms.code import HighlightLanguageVisitor -from sphinx.writers.html5 import HTML5Translator -from sphinx.application import Sphinx -from sphinx.locale import _ - - -def re_visit_literal_block( - self: HighlightLanguageVisitor, node: nodes.literal_block -) -> None: - setting = self.settings[-1] - - node.parent["classes"] += ["highlight"] - if "language" not in node: - node["language"] = setting.language - node["force"] = setting.force - if "linenos" not in node: - lines = node.astext().count("\n") - node["linenos"] = lines >= setting.lineno_threshold - 1 - - -def re_visit_caption(self: HTML5Translator, node: nodes.Element) -> None: - attributes = {"class": "caption-text"} - if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): - self.body.append('
') - attributes["class"] += " filename" - else: - super().visit_caption(node) - self.add_fignumber(node.parent) - self.body.append(self.starttag(node, "span", **attributes)) - - -def re_depart_caption(self: HTML5Translator, node: nodes.Element) -> None: - if not isinstance(node.parent, nodes.container) and not node.parent.get( - "literal_block" - ): - self.body.append("") - - # append permalink if available - if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): - self.add_permalink_ref(node.parent, _("Permalink to this code")) - self.body.append("") - elif isinstance(node.parent, nodes.figure): - self.add_permalink_ref(node.parent, _("Permalink to this image")) - elif node.parent.get("toctree"): - self.add_permalink_ref(node.parent.parent, _("Permalink to this toctree")) - - if isinstance(node.parent, nodes.container) and node.parent.get("literal_block"): - self.body.append("
\n") - else: - super().depart_caption(node) - - -def setup(app: Sphinx): - HighlightLanguageVisitor.visit_literal_block = re_visit_literal_block - HTML5Translator.visit_caption = re_visit_caption - HTML5Translator.depart_caption = re_depart_caption diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index 86104f7ed..c3136ca1d 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -45,7 +45,7 @@ $objinfo-icon-size: 16px; font-weight: 700; } - a.reference > .sig-name { + a.reference > span { color: var(--md-typeset-a-color); &:hover { @@ -65,18 +65,36 @@ $objinfo-icon-size: 16px; color: var(--md-accent-fg-color); } + // Ensure each parameter starts on a new line and is indented. &.sig-wrap { - .sig-param { - // Ensure each parameter starts on a new line and is indented. - &::before { - white-space: pre; - // 5 spaces below result in 4 spaces of indent. - // For some reason one space is lost. + .sig-param, + .n { + + .kt, + + .k, + + .n:not(.sig-param) { + &::before { + white-space: pre; + // 5 spaces below result in 4 spaces of indent. + // For some reason one space is lost. + content: "\A "; + } + } + } + + .sig-param:not(:first-of-type) > .n:first-child::before { + content: "\A "; + white-space: pre; + } + + .sig-paren:not(:last-of-type){ + // Ensure the first paren ends the line + &::after { content: "\A "; + white-space: pre; } } - .sig-param + .sig-paren { + .sig-paren:last-of-type { // Ensure the final paren starts on a new line &::before { white-space: pre; From 6c931a90e0f33656771a79d4010f500b68e89862 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 5 Apr 2022 16:31:15 -0700 Subject: [PATCH 10/31] pleasing stylelint --- src/assets/stylesheets/main/_api.scss | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index c3136ca1d..6b4d0cbc7 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -82,15 +82,15 @@ $objinfo-icon-size: 16px; } .sig-param:not(:first-of-type) > .n:first-child::before { - content: "\A "; white-space: pre; + content: "\A "; } - .sig-paren:not(:last-of-type){ + .sig-paren:not(:last-of-type) { // Ensure the first paren ends the line &::after { - content: "\A "; white-space: pre; + content: "\A "; } } From b03e916d6f636ddbdc06fcfc99d85a691afabce4 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 5 Apr 2022 16:35:06 -0700 Subject: [PATCH 11/31] pleasing pylint --- sphinx_immaterial/apidoc_formatting.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_immaterial/apidoc_formatting.py b/sphinx_immaterial/apidoc_formatting.py index 362678041..f0688e698 100644 --- a/sphinx_immaterial/apidoc_formatting.py +++ b/sphinx_immaterial/apidoc_formatting.py @@ -195,7 +195,7 @@ def depart_caption(self, node: docutils.nodes.Element) -> None: if not isinstance( node.parent, docutils.nodes.container ) and not node.parent.get("literal_block"): - # only append ending tag if parent is not a literal-block. + # only append ending tag if parent is not a literal-block. # Because all elements in the caption should be within a span element self.body.append("") From 3fe60a0b996a0ae5bb1e7db0e10cdd0166fd653d Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 7 Apr 2022 00:50:51 -0700 Subject: [PATCH 12/31] polish & remove experimental button.py - CSS additions consolidated and revised - result directive (and corresponding CSS) - various improvements to the docs --- docs/_static/extra_css.css | 21 -- docs/additional_samples.rst | 304 ++++++++++++----------- docs/buttons.rst | 31 --- docs/conf.py | 23 +- docs/demo_api.rst | 32 +-- docs/index.rst | 5 +- docs/mermaid_diagrams.rst | 9 + docs/specimen.rst | 25 +- docs/test_py_module/test.py | 4 +- sphinx_immaterial/button.py | 158 ------------ sphinx_immaterial/theme_result.py | 21 +- src/assets/stylesheets/main/_api.scss | 7 +- src/assets/stylesheets/main/_sphinx.scss | 30 +++ 13 files changed, 249 insertions(+), 421 deletions(-) delete mode 100644 docs/buttons.rst delete mode 100644 sphinx_immaterial/button.py diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index f106d67fa..531f0a83a 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -24,27 +24,6 @@ border-radius: 36px; } -/* **************************** theme-results directive special ******************** */ - -.result .results-prefix { - margin-bottom: 1em; - margin-top: 0.1rem; - background-color: var(--md-code-bg-color); - overflow: visible; - border-bottom-left-radius: 0.5rem; - border-bottom-right-radius: 0.5rem; - padding: 0 0.5rem; -} - -.md-typeset :is(.highlight, .highlighttable, .literal-block-wrapper) + .result { - border: .05rem solid var(--md-code-bg-color); - border-bottom-left-radius: .1rem; - border-bottom-right-radius: .1rem; - border-top-width: .1rem; - margin-top: -1.125em; - overflow: visible; - padding: 0 1em; -} /* ************************* my-special-key style ************************************* */ .md-typeset kbd.key-my-special-key, diff --git a/docs/additional_samples.rst b/docs/additional_samples.rst index 329508d16..d68114088 100644 --- a/docs/additional_samples.rst +++ b/docs/additional_samples.rst @@ -7,7 +7,6 @@ Various examples of styling applied to Sphinx constructs. You can view the `source <./_sources/examples.txt>`_ of this page to see the specific reStructuredText used to create these examples. - Headings ======== This is a first level heading (``h1``). @@ -23,79 +22,87 @@ This is a third level heading (``h3``). Code ==== -The theme uses pygments for ``inline code text`` and -:: - multiline - code text +.. result:: + + The theme uses pygments for ``inline code text`` and + :: + + multiline + code text Here's an included example with line numbers. -.. literalinclude:: ../sphinx_immaterial/autodoc_property_type.py - :caption: source from this theme in *sphinx_immaterial/autodoc_property_type.py* - :linenos: +.. result:: + + .. literalinclude:: ../sphinx_immaterial/autodoc_property_type.py + :caption: source from this theme in *sphinx_immaterial/autodoc_property_type.py* + :linenos: It also works with existing Sphinx highlighting: -.. code-block:: html +.. result:: + + .. code-block:: html - - Hello World - + + Hello World + -.. code-block:: python + .. code-block:: python - def hello(): - """Greet.""" - return "Hello World" + def hello(): + """Greet.""" + return "Hello World" -.. code-block:: javascript + .. code-block:: javascript - /** - * Greet. - */ - function hello(): { - return "Hello World"; - } + /** + * Greet. + */ + function hello(): { + return "Hello World"; + } Footnotes ========= -I have footnoted a first item [#f1]_ and second item [#f2]_. -This also references the second item [#f2]_. -.. rubric:: Footnotes -.. [#f1] My first footnote. -.. [#f2] My second footnote. +.. result:: -Icons -===== -The following template HTML: + I have footnoted a first item [#f1]_ and second item [#f2]_. + This also references the second item [#f2]_. -.. code-block:: html + .. rubric:: Footnotes + .. [#f1] My first footnote. + .. [#f2] My second footnote. - +Icons +===== -translates to a the site's icon: +.. result:: The following raw HTML + :output-prefix: translates to the icon: -.. raw:: html + .. raw:: html - + The material icon font provides hundreds to choose from. You can use the ```` tag or the ```` tag. -.. raw:: html +.. result:: - - - - - - - - - - + .. raw:: html + + + + + + + + + + + Tables @@ -109,30 +116,32 @@ using ``.. cssclass:: custom-class`` and then add it to your configuration's Grid ---- -A grid table: -+------------------------+------------+----------+----------+ -| Header1 | Header2 | Header3 | Header4 | -+========================+============+==========+==========+ -| row1, cell1 | cell2 | cell3 | cell4 | -+------------------------+------------+----------+----------+ -| row2 ... | ... | ... | | -+------------------------+------------+----------+----------+ -| ... | ... | ... | | -+------------------------+------------+----------+----------+ +.. result:: A grid table: + + +------------------------+------------+----------+----------+ + | Header1 | Header2 | Header3 | Header4 | + +========================+============+==========+==========+ + | row1, cell1 | cell2 | cell3 | cell4 | + +------------------------+------------+----------+----------+ + | row2 ... | ... | ... | | + +------------------------+------------+----------+----------+ + | ... | ... | ... | | + +------------------------+------------+----------+----------+ Simple ------ -A simple table: -===== ===== ======= -H1 H2 H3 -===== ===== ======= -cell1 cell2 cell3 -... ... ... -... ... ... -===== ===== ======= +.. result:: A simple table: + + ===== ===== ======= + H1 H2 H3 + ===== ===== ======= + cell1 cell2 cell3 + ... ... ... + ... ... ... + ===== ===== ======= User-styled Table ----------------- @@ -146,80 +155,90 @@ User-styled Table This is feature demonstration. There is no css for the plain class, and so this is completely unstyled. -.. cssclass:: plain -===== ====== ======= -User Styled Table -===== ====== ======= -cell1 cell2 cell3 -... ... ... -... ... ... -===== ====== ======= +.. result:: + + .. cssclass:: plain + + ===== ====== ======= + User Styled Table + ===== ====== ======= + cell1 cell2 cell3 + ... ... ... + ... ... ... + ===== ====== ======= List Tables ----------- -.. list-table:: A List Table - :header-rows: 1 +.. result:: + + .. list-table:: A List Table + :header-rows: 1 - * - Column 1 - - Column 2 - * - Item 1 - - Item 2 + * - Column 1 + - Column 2 + * - Item 1 + - Item 2 Alignment ~~~~~~~~~ -.. list-table:: Center Aligned - :header-rows: 1 - :align: center - - * - Column 1 - - Column 2 - * - Item 1 - - Item 2 - - -.. list-table:: Right Aligned - :widths: 15 10 30 - :header-rows: 1 - :align: right - - * - Treat - - Quantity - - Description - * - Albatross - - 2.99 - - On a stick! - * - Crunchy Frog - - 1.49 - - If we took the bones out - * - Gannet Ripple - - 1.99 - - On a stick! +.. result:: + + .. list-table:: Center Aligned + :header-rows: 1 + :align: center + + * - Column 1 + - Column 2 + * - Item 1 + - Item 2 + + +.. result:: + + .. list-table:: Right Aligned + :widths: 15 10 30 + :header-rows: 1 + :align: right + + * - Treat + - Quantity + - Description + * - Albatross + - 2.99 + - On a stick! + * - Crunchy Frog + - 1.49 + - If we took the bones out + * - Gannet Ripple + - 1.99 + - On a stick! Code Documentation ================== -An example Python function. -.. py:function:: format_exception(etype, value, tb[, limit=None]) +.. result:: An example Python function. - Format the exception with a traceback. + .. py:function:: format_exception(etype, value, tb[, limit=None]) - :param etype: exception type - :param value: exception value - :param tb: traceback object - :param limit: maximum number of stack frames to show - :type limit: integer or None - :rtype: list of strings + Format the exception with a traceback. -An example JavaScript function. + :param etype: exception type + :param value: exception value + :param tb: traceback object + :param limit: maximum number of stack frames to show + :type limit: integer or None + :rtype: list of strings -.. js:class:: MyAnimal(name[, age]) +.. result:: An example JavaScript function. - :param string name: The name of the animal - :param number age: an optional age for the animal + .. js:class:: MyAnimal(name[, age]) + + :param string name: The name of the animal + :param number age: an optional age for the animal Glossaries ========== @@ -239,37 +258,44 @@ Glossaries Math ==== -.. math:: +.. result:: - (a + b)^2 = a^2 + 2ab + b^2 + .. math:: - (a - b)^2 = a^2 - 2ab + b^2 + (a + b)^2 = a^2 + 2ab + b^2 -.. math:: + (a - b)^2 = a^2 - 2ab + b^2 - (a + b)^2 &= (a + b)(a + b) \\ - &= a^2 + 2ab + b^2 +.. result:: + .. math:: + + (a + b)^2 &= (a + b)(a + b) \\ + &= a^2 + 2ab + b^2 -.. math:: - :nowrap: +.. result:: - \begin{eqnarray} - y & = & ax^2 + bx + c \\ - f(x) & = & x^2 + 2xy + y^2 - \end{eqnarray} + .. math:: + :nowrap: + + \begin{eqnarray} + y & = & ax^2 + bx + c \\ + f(x) & = & x^2 + 2xy + y^2 + \end{eqnarray} Production Lists ================ -.. productionlist:: - try_stmt: try1_stmt | try2_stmt - try1_stmt: "try" ":" `suite` - : ("except" [`expression` ["," `target`]] ":" `suite`)+ - : ["else" ":" `suite`] - : ["finally" ":" `suite`] - try2_stmt: "try" ":" `suite` - : "finally" ":" `suite` +.. result:: + + .. productionlist:: + try_stmt: try1_stmt | try2_stmt + try1_stmt: "try" ":" `suite` + : ("except" [`expression` ["," `target`]] ":" `suite`)+ + : ["else" ":" `suite`] + : ["finally" ":" `suite`] + try2_stmt: "try" ":" `suite` + : "finally" ":" `suite` Sub-pages ========= diff --git a/docs/buttons.rst b/docs/buttons.rst deleted file mode 100644 index ae3dcf3ca..000000000 --- a/docs/buttons.rst +++ /dev/null @@ -1,31 +0,0 @@ - -Buttons -=========== - -Directives ------------ - -.. result:: Some examples of the button directives - :output-prefix: - - .. md-button-primary:: `keys_extension_role` - :class: lcars-button - - Clickable buttons are next! - - .. md-button:: http://www.example.com - :class: lcars-button - - some text - -Roles ------------ - -.. result:: Some examples of the button roles. - :output-prefix: Which produces something like this: - - :md-button:`https://www.example.com` - - :ref:`keys ext role ` - - :md-button-primary:`keys ext role ` diff --git a/docs/conf.py b/docs/conf.py index 9b5cec569..80dea063f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -37,7 +37,6 @@ "sphinxcontrib.details.directive", "sphinx_immaterial.theme_result", "sphinx_immaterial.kbd_keys", - "sphinx_immaterial.button", ] intersphinx_mapping = { @@ -67,26 +66,20 @@ # -- Options for HTML output ------------------------------------------------- -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# - # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named 'default.css' will overwrite the builtin 'default.css'. html_static_path = ["_static"] -html_css_files = [ - "extra_css.css", - # "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.4/css/all.min.css", -] +html_css_files = ["extra_css.css"] +html_last_updated_fmt = "" +html_title = "Sphinx-Immaterial" +html_favicon = "_static/images/favicon.ico" # colored version of material/bookshelf.svg +html_logo = "_static/images/Ybin.gif" # from https://gifer.com/en/Ybin -# -- HTML theme settings ------------------------------------------------ +# -- HTML theme specific settings ------------------------------------------------ extensions.append("sphinx_immaterial") -html_title = "Sphinx-Immaterial" html_theme = "sphinx_immaterial" -html_favicon = "_static/images/favicon.ico" # colored version of material/bookshelf.svg -html_logo = "_static/images/Ybin.gif" # from https://gifer.com/en/Ybin # material theme options (see theme.conf for more information) html_theme_options = { @@ -150,10 +143,6 @@ "toc_title_is_page_title": True, } # end html_theme_options -html_last_updated_fmt = "" -html_use_index = False -html_domain_indices = False - # ---- Other documentation options ------------------------- todo_include_todos = True diff --git a/docs/demo_api.rst b/docs/demo_api.rst index 78e37cbd5..3ae3dd31c 100644 --- a/docs/demo_api.rst +++ b/docs/demo_api.rst @@ -135,35 +135,17 @@ JavaScript API Generated Index =============== -Part of the sphinx build process in generate and index file: :ref:`genindex`. - - -Optional parameter args -======================= - -At this point optional parameters `cannot be generated from code`_. -However, some projects will manually do it, like so: - -This example comes from `django-payments module docs`_. - .. result:: - .. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl']) - - This backend implements payments using a popular Polish gateway, `Dotpay.pl `_. - - Due to API limitations there is no support for transferring purchased items. - - - :param seller_id: Seller ID assigned by Dotpay - :param pin: PIN assigned by Dotpay - :param channel: Default payment channel (consult reference guide) - :param lang: UI language - :param lock: Whether to disable channels other than the default selected above + A generated index (:ref:`genindex`) is part of the Sphinx build process, unless + `html_use_index` is set to `False`. -.. _cannot be generated from code: https://groups.google.com/forum/#!topic/sphinx-users/_qfsVT5Vxpw -.. _django-payments module docs: http://django-payments.readthedocs.org/en/latest/modules.html#payments.authorizenet.AuthorizeNetProvide + Sphinx also allows indexing by domain (programming language), as seen in the + :ref:`modindex` for the demo Python module that is documented on this page. +.. note:: + This theme does not support a separate search page (usually referenced with + ``:ref:`search``), since the search is accessible in the site's navigation bar. Data ==== diff --git a/docs/index.rst b/docs/index.rst index 90021d084..d58f68dd7 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -60,8 +60,8 @@ or ``theme.conf`` for more details. :class: example .. literalinclude:: ./conf.py - :start-at: # -- HTML theme settings ------------------------------------------------ - :end-before: # ---- Other documentation options ------------------------- + :start-at: # -- HTML theme specific settings + :end-before: # ---- Other documentation options .. toctree:: @@ -73,7 +73,6 @@ or ``theme.conf`` for more details. mermaid_diagrams task_lists keys - buttons .. toctree:: :caption: Examples and Uses diff --git a/docs/mermaid_diagrams.rst b/docs/mermaid_diagrams.rst index 28fd5aa24..0b1107831 100644 --- a/docs/mermaid_diagrams.rst +++ b/docs/mermaid_diagrams.rst @@ -20,6 +20,15 @@ directive that exposes the underlying implementation in mkdocs-material theme. A space delimited list of qualified names that get used as the HTML element's ``class`` attribute. + .. hint:: + You can use this option to specify ``text-align`` property via the following + CSS classes: + + - ``align-right`` sets the ``text-align`` property to ``right``. + - ``align-left`` sets the ``text-align`` property to ``left``. + - ``align-center`` sets the ``text-align`` property to ``center``. + + .. rst:directive:option:: name :type: string diff --git a/docs/specimen.rst b/docs/specimen.rst index 4682d2cb0..8d51c9e2b 100644 --- a/docs/specimen.rst +++ b/docs/specimen.rst @@ -373,23 +373,28 @@ Images Default Alignment ~~~~~~~~~~~~~~~~~ +.. result:: -.. image:: desert-flower.jpg - :alt: Default image + .. image:: desert-flower.jpg + :alt: Default image Center Alignment ~~~~~~~~~~~~~~~~ -.. image:: desert-flower.jpg - :alt: Centered Image, 80% scale - :scale: 80% - :align: center +.. result:: + + .. image:: desert-flower.jpg + :alt: Centered Image, 80% scale + :scale: 80% + :align: center Right Alignment ~~~~~~~~~~~~~~~ -.. image:: desert-flower.jpg - :alt: Right Image, 60% scale - :scale: 60% - :align: right +.. result:: + + .. image:: desert-flower.jpg + :alt: Right Image, 60% scale + :scale: 60% + :align: right Math again ---------- diff --git a/docs/test_py_module/test.py b/docs/test_py_module/test.py index 3c8d656e2..58ebd4ffb 100644 --- a/docs/test_py_module/test.py +++ b/docs/test_py_module/test.py @@ -46,11 +46,11 @@ def __init__(self, qux, spam=False): """Start the Foo. :param qux: The first argument to initialize class. - :type qux: string + :type qux: str :param spam: Spam me yes or no... :type spam: bool - """ + #: Doc comment for instance attribute qux. self.qux = 3 diff --git a/sphinx_immaterial/button.py b/sphinx_immaterial/button.py deleted file mode 100644 index 983efab27..000000000 --- a/sphinx_immaterial/button.py +++ /dev/null @@ -1,158 +0,0 @@ -"""A simple directive that creates a HTML ```` element.""" - -from typing import List, Any, Tuple -from docutils.parsers.rst import directives, states -from docutils import nodes -from sphinx.application import Sphinx -from sphinx.util.docutils import SphinxDirective -from sphinx.roles import AnyXRefRole -from sphinx.writers.html import HTMLTranslator -from sphinx.util.logging import getLogger - -LOGGER = getLogger(__name__) - - -class a_tag_node(nodes.container): - pass - - -def visit_a_tag(self: HTMLTranslator, node: a_tag_node): - attributes = {"class": " ".join(node["classes"])} - if "href" in node: - attributes["href"] = node["href"] - if "reftarget" in node: - attributes["href"] = node["reftarget"] - self.body.append(self.starttag(node, "a", **attributes)) - - -def depart_a_tag(self: HTMLTranslator, node: a_tag_node): - self.body.append("") - - -class MaterialButtonRole(AnyXRefRole): - def result_nodes( - self, - document: nodes.document, - env: "BuildEnvironment", - node: nodes.Element, - is_ref: bool, - ) -> Tuple[List[nodes.Node], List[str]]: - node["classes"] += ["md-button"] - return super().result_nodes(document, env, node, is_ref) - - -class MaterialButtonPrimaryRole(AnyXRefRole): - def result_nodes( - self, - document: nodes.document, - env: "BuildEnvironment", - node: nodes.Element, - is_ref: bool, - ) -> Tuple[List[nodes.Node], List[str]]: - node["classes"] += ["md-button", "md-button--primary"] - return super().result_nodes(document, env, node, is_ref) - - -class BasicButton(SphinxDirective): - - has_content = True - required_arguments = 1 - option_spec = { - "name": directives.unchanged, - "class": directives.class_option, - "is-md": directives.flag, - "is-md-primary": directives.flag, - } - - def run(self) -> List[nodes.Node]: - """Run the directive.""" - default_cls = [] - if self.options is not None: - default_cls = self.options.get("class", []) - if "is-md" in self.options: - default_cls.append("md-button") - if "is-md-primary" in self.options: - default_cls.append("md-button--primary") - a_tag = a_tag_node("", classes=default_cls, href=self.arguments[0]) - if self.options.get("name", ""): - self.add_name(a_tag) - textnodes, _ = self.state.inline_text(self.arguments[0], self.lineno) - if not self.content: - a_tag += textnodes - else: - a_tag["alt"] = textnodes - for line in self.content: - content, _ = self.state.inline_text(line, self.content_offset) - a_tag += content - return [a_tag] - - -# pylint: disable=too-many-arguments -class MaterialButton(BasicButton): - def __init__( - self, - name: str, - arguments: list[Any], - options: dict[str, Any], - content: list[str], - lineno: int, - content_offset: int, - block_text: str, - state: states.RSTState, - state_machine: states.RSTStateMachine, - ) -> None: - if options is not None: - options["is-md"] = True - else: - options = {"is-md": True} - super().__init__( - name, - arguments, - options, - content, - lineno, - content_offset, - block_text, - state, - state_machine, - ) - - -class MaterialButtonPrimary(MaterialButton): - def __init__( - self, - name: str, - arguments: list[Any], - options: dict[str, Any], - content: list[str], - lineno: int, - content_offset: int, - block_text: str, - state: states.RSTState, - state_machine: states.RSTStateMachine, - ) -> None: - if options is not None: - options["is-md-primary"] = True - else: - options = {"is-md-primary": True} - super().__init__( - name, - arguments, - options, - content, - lineno, - content_offset, - block_text, - state, - state_machine, - ) - - -def setup(app: Sphinx): - """Setup the extension.""" - app.add_directive("button", BasicButton) - app.add_directive("md-button", MaterialButton) - app.add_directive("md-button-primary", MaterialButtonPrimary) - app.add_node(a_tag_node, html=(visit_a_tag, depart_a_tag)) - app.add_role("md-button", MaterialButtonRole()) - app.add_role("md-button-primary", MaterialButtonPrimaryRole()) diff --git a/sphinx_immaterial/theme_result.py b/sphinx_immaterial/theme_result.py index 2de660d8f..cbe294fa8 100644 --- a/sphinx_immaterial/theme_result.py +++ b/sphinx_immaterial/theme_result.py @@ -21,19 +21,15 @@ class ResultsDirective(SphinxDirective): def run(self): """Run the directive.""" container_node = nodes.container( - "", is_div=True, classes=self.options.get("class", []) + ["results"] + "", classes=self.options.get("class", []) + ["results"] ) code = "\n".join(self.content) - literal_node = nodes.literal_block( - code, code, caption="" if not self.arguments else self.arguments[0] - ) + literal_node = nodes.literal_block(code, code) literal_node["language"] = "rst" - literal_node["classes"] += ["highlight"] if self.arguments: - literal_node = container_wrapper( - self, literal_node=literal_node, caption=self.arguments[0] - ) - results_div = nodes.container("", is_div=True, classes=["result"]) + literal_node = container_wrapper(self, literal_node, self.arguments[0]) + container_node += literal_node + if "output-prefix" in self.options: out_prefix = nodes.container("", classes=["results-prefix"]) prefix = self.options.get("output-prefix", "") @@ -41,10 +37,13 @@ def run(self): prefix = "Which renders the following content:" textnodes, _ = self.state.inline_text(prefix, self.lineno) out_prefix += textnodes - results_div += out_prefix + container_node += out_prefix + + # the `result` CSS class is theme specific (as used by mkdocs-material theme) + results_div = nodes.container("", classes=["result"]) self.state.nested_parse(self.content, self.content_offset, results_div) - container_node += literal_node container_node += results_div + self.set_source_info(container_node) self.add_name(container_node) return [container_node] diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index 6b4d0cbc7..99210b544 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -81,14 +81,14 @@ $objinfo-icon-size: 16px; } } - .sig-param:not(:first-of-type) > .n:first-child::before { + .sig-param > .n:first-child::before { white-space: pre; content: "\A "; } - .sig-paren:not(:last-of-type) { + .sig-paren + span { // Ensure the first paren ends the line - &::after { + &::before { white-space: pre; content: "\A "; } @@ -242,7 +242,6 @@ table.longtable.docutils.data.align-default { } // a rule to reset margin for code-blocks with a caption -// works best with sphinx_immaterial.patch_literal_blocks extension .md-typeset .code-block-caption + .notranslate pre, .md-typeset .code-block-caption + .notranslate .highlighttable { margin-top: 0; diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index c3b62a7e1..4d8d86f81 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -79,4 +79,34 @@ .rubric { font-weight: 700; } + + // theme-results directive special rules + .results .results-prefix { + margin-top: -1em; + padding: px2em(9px, 13.6px) px2em(16px, 13.6px); + font-weight: 700; + font-size: px2em(13.6px); + background-color: var(--md-code-bg-color); + } + + :is(.highlight, .highlighttable, .literal-block-wrapper), + div[class^="highlight-"], + .results-prefix { + + .result { + border: 0.05rem solid var(--md-code-bg-color); + border-bottom-left-radius: 0.1rem; + border-bottom-right-radius: 0.1rem; + border-top-width: 0.1rem; + margin-top: -1em; + overflow: visible; + padding: 0 1em; + } + } + + .results-prefix { + +.result { + margin-top: 0; + } + } + } From 86f1c0d95e5e60274e146d88631bcf0c4863aae0 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 7 Apr 2022 01:04:23 -0700 Subject: [PATCH 13/31] pleasing stylelint --- .gitattributes | 8 ++++++++ src/assets/stylesheets/main/_sphinx.scss | 6 +++--- 2 files changed, 11 insertions(+), 3 deletions(-) create mode 100644 .gitattributes diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..ec8970737 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,8 @@ +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +*.py text eol=lf +*.rst text eol=lf +*.scss text eol=lf \ No newline at end of file diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index 4d8d86f81..9df301729 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -94,12 +94,12 @@ .results-prefix { + .result { border: 0.05rem solid var(--md-code-bg-color); - border-bottom-left-radius: 0.1rem; - border-bottom-right-radius: 0.1rem; border-top-width: 0.1rem; + border-bottom-right-radius: 0.1rem; + border-bottom-left-radius: 0.1rem; margin-top: -1em; - overflow: visible; padding: 0 1em; + overflow: visible; } } From 454dc69aca7500ee1325ac34753968679193ffce Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 7 Apr 2022 01:09:05 -0700 Subject: [PATCH 14/31] still pleasing stylelint --- src/assets/stylesheets/main/_sphinx.scss | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index 9df301729..40777aae4 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -93,11 +93,11 @@ div[class^="highlight-"], .results-prefix { + .result { + margin-top: -1em; border: 0.05rem solid var(--md-code-bg-color); border-top-width: 0.1rem; border-bottom-right-radius: 0.1rem; border-bottom-left-radius: 0.1rem; - margin-top: -1em; padding: 0 1em; overflow: visible; } @@ -108,5 +108,4 @@ margin-top: 0; } } - } From a0fe3b20700d80a483979cb55be19793f211b8d2 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 7 Apr 2022 01:10:53 -0700 Subject: [PATCH 15/31] hopefully the last stylelint fix --- src/assets/stylesheets/main/_sphinx.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index 40777aae4..f5c4ba63c 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -94,11 +94,11 @@ .results-prefix { + .result { margin-top: -1em; + padding: 0 1em; border: 0.05rem solid var(--md-code-bg-color); border-top-width: 0.1rem; border-bottom-right-radius: 0.1rem; border-bottom-left-radius: 0.1rem; - padding: 0 1em; overflow: visible; } } From 21624e28855ba9a057bebb6ab9d4c264ef2d427d Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 7 Apr 2022 01:12:53 -0700 Subject: [PATCH 16/31] [stylelint] WTH is with property ordering in scss --- src/assets/stylesheets/main/_sphinx.scss | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index f5c4ba63c..7eb0fb232 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -95,11 +95,11 @@ + .result { margin-top: -1em; padding: 0 1em; + overflow: visible; border: 0.05rem solid var(--md-code-bg-color); border-top-width: 0.1rem; border-bottom-right-radius: 0.1rem; border-bottom-left-radius: 0.1rem; - overflow: visible; } } From b1f58d02a078d4a17fea2a62680be7371e742c6e Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Mon, 11 Apr 2022 16:59:44 -0700 Subject: [PATCH 17/31] adjust custon keys' CSS for chrome --- docs/_static/extra_css.css | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index 531f0a83a..5e1a889d8 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -34,7 +34,8 @@ .md-typeset kbd.key-git::before { content: "██"; - --webmask-image: var(--md-icon__fa-git); + -webkit-mask-image: var(--md-icon__fa-git); + -webkit-mask-repeat: no-repeat; mask-image: var(--md-icon__fa-git); mask-repeat: no-repeat; } From d411a7abf56dc06f0aa72d36c40e71b4001678d4 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Mon, 11 Apr 2022 17:27:42 -0700 Subject: [PATCH 18/31] remove button testing CSS --- docs/_static/extra_css.css | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index 5e1a889d8..f79ccee51 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -18,12 +18,6 @@ --md-icon__fa-bitbucket: url('data:image/svg+xml;charset=utf-8,'); } -/* **************************** test buttons' LCARS style ************************** */ - -.md-typeset a.lcars-button { - border-radius: 36px; -} - /* ************************* my-special-key style ************************************* */ .md-typeset kbd.key-my-special-key, From 50629a2621ae5960602ecc6103e688c6063ae374 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Mon, 11 Apr 2022 18:24:24 -0700 Subject: [PATCH 19/31] use descrptive directive name --- docs/additional_samples.rst | 36 +++++++++++++++---------------- docs/admonitions.rst | 34 ++++++++++++++--------------- docs/content_tabs.rst | 4 ++-- docs/demo_api.rst | 30 +++++++++++++------------- docs/keys.rst | 6 +++--- docs/mermaid_diagrams.rst | 12 +++++------ docs/specimen.rst | 6 +++--- docs/task_lists.rst | 4 ++-- sphinx_immaterial/theme_result.py | 2 +- 9 files changed, 67 insertions(+), 67 deletions(-) diff --git a/docs/additional_samples.rst b/docs/additional_samples.rst index d68114088..480104f2a 100644 --- a/docs/additional_samples.rst +++ b/docs/additional_samples.rst @@ -23,7 +23,7 @@ This is a third level heading (``h3``). Code ==== -.. result:: +.. rst-example:: The theme uses pygments for ``inline code text`` and :: @@ -33,7 +33,7 @@ Code Here's an included example with line numbers. -.. result:: +.. rst-example:: .. literalinclude:: ../sphinx_immaterial/autodoc_property_type.py :caption: source from this theme in *sphinx_immaterial/autodoc_property_type.py* @@ -41,7 +41,7 @@ Here's an included example with line numbers. It also works with existing Sphinx highlighting: -.. result:: +.. rst-example:: .. code-block:: html @@ -67,7 +67,7 @@ It also works with existing Sphinx highlighting: Footnotes ========= -.. result:: +.. rst-example:: I have footnoted a first item [#f1]_ and second item [#f2]_. This also references the second item [#f2]_. @@ -79,7 +79,7 @@ Footnotes Icons ===== -.. result:: The following raw HTML +.. rst-example:: The following raw HTML :output-prefix: translates to the icon: .. raw:: html @@ -89,7 +89,7 @@ Icons The material icon font provides hundreds to choose from. You can use the ```` tag or the ```` tag. -.. result:: +.. rst-example:: .. raw:: html @@ -117,7 +117,7 @@ using ``.. cssclass:: custom-class`` and then add it to your configuration's Grid ---- -.. result:: A grid table: +.. rst-example:: A grid table: +------------------------+------------+----------+----------+ | Header1 | Header2 | Header3 | Header4 | @@ -133,7 +133,7 @@ Grid Simple ------ -.. result:: A simple table: +.. rst-example:: A simple table: ===== ===== ======= H1 H2 H3 @@ -156,7 +156,7 @@ User-styled Table this is completely unstyled. -.. result:: +.. rst-example:: .. cssclass:: plain @@ -171,7 +171,7 @@ User-styled Table List Tables ----------- -.. result:: +.. rst-example:: .. list-table:: A List Table :header-rows: 1 @@ -184,7 +184,7 @@ List Tables Alignment ~~~~~~~~~ -.. result:: +.. rst-example:: .. list-table:: Center Aligned :header-rows: 1 @@ -196,7 +196,7 @@ Alignment - Item 2 -.. result:: +.. rst-example:: .. list-table:: Right Aligned :widths: 15 10 30 @@ -220,7 +220,7 @@ Code Documentation ================== -.. result:: An example Python function. +.. rst-example:: An example Python function. .. py:function:: format_exception(etype, value, tb[, limit=None]) @@ -233,7 +233,7 @@ Code Documentation :type limit: integer or None :rtype: list of strings -.. result:: An example JavaScript function. +.. rst-example:: An example JavaScript function. .. js:class:: MyAnimal(name[, age]) @@ -258,7 +258,7 @@ Glossaries Math ==== -.. result:: +.. rst-example:: .. math:: @@ -266,14 +266,14 @@ Math (a - b)^2 = a^2 - 2ab + b^2 -.. result:: +.. rst-example:: .. math:: (a + b)^2 &= (a + b)(a + b) \\ &= a^2 + 2ab + b^2 -.. result:: +.. rst-example:: .. math:: :nowrap: @@ -286,7 +286,7 @@ Math Production Lists ================ -.. result:: +.. rst-example:: .. productionlist:: try_stmt: try1_stmt | try2_stmt diff --git a/docs/admonitions.rst b/docs/admonitions.rst index bc228a317..fe476f067 100644 --- a/docs/admonitions.rst +++ b/docs/admonitions.rst @@ -11,7 +11,7 @@ Most of the admonitions that the mkdocs-material theme supports were "borrowed" admonitions defined in the reStructuredText specifications. You may recognize them from usage in other sphinx-based themes. They are: -.. result:: ``note``, ``todo``, ``seealso`` +.. rst-example:: ``note``, ``todo``, ``seealso`` .. seealso:: This admonition is specific to Sphinx directives and not defined in the rST specifications @@ -19,17 +19,17 @@ usage in other sphinx-based themes. They are: ``note`` and ``todo`` are admonitions defined by the rST specifications. -.. result:: ``tip``, ``hint``, ``important`` +.. rst-example:: ``tip``, ``hint``, ``important`` .. important:: It is **important** to correctly use admonitions. -.. result:: ``attention``, ``caution``, ``warning`` +.. rst-example:: ``attention``, ``caution``, ``warning`` .. warning:: This is a **warning**. -.. result:: ``danger``, ``error`` +.. rst-example:: ``danger``, ``error`` .. error:: You have made a grave **error**. @@ -49,7 +49,7 @@ shown to demonstrate using the ``:class:`` option of generic admonitions. styling to work. Otherwise, the admonition will look like a `note` (as that is the default fallback style). -.. result:: ``todo``, ``info`` +.. rst-example:: ``todo``, ``info`` .. admonition:: Info :class: info @@ -57,49 +57,49 @@ shown to demonstrate using the ``:class:`` option of generic admonitions. Thanks to the mkdocs-material theme, the ``todo`` class is also an alias of the ``info`` class when not using the `.. todo:: ` directive. -.. result:: ``abstract``, ``summary``, ``tldr`` +.. rst-example:: ``abstract``, ``summary``, ``tldr`` .. admonition:: TL;DR :class: tldr The ``:class: tldr`` part is important. -.. result:: ``success``, ``check``, ``done`` +.. rst-example:: ``success``, ``check``, ``done`` .. admonition:: Accomplished :class: done This style is used for ``success``, ``check``, ``done`` CSS classes. -.. result:: ``question``, ``help``, ``faq`` +.. rst-example:: ``question``, ``help``, ``faq`` .. admonition:: FAQ :class: faq Helpful advice goes here. -.. result:: ``failure``, ``fail``, ``missing`` +.. rst-example:: ``failure``, ``fail``, ``missing`` .. admonition:: Something Missing :class: missing We expected some loss of feature-coverage. -.. result:: ``bug`` +.. rst-example:: ``bug`` .. admonition:: Known Bug :class: bug Bug reported data/conclusion. -.. result:: ``example`` +.. rst-example:: ``example`` .. admonition:: Example Admonition :class: example Example Body. -.. result:: ``cite``, ``quote`` +.. rst-example:: ``cite``, ``quote`` .. admonition:: Unknown Quote :class: quote @@ -125,7 +125,7 @@ The `sphinxcontrib-details-directive extension`_ should be added to conf.py's ex If the ``:class:`` option is not supplied to the ``details`` directive then the admonition style falls back to a `note` admonition style. -.. result:: +.. rst-example:: .. details:: Open by default :class: example @@ -133,7 +133,7 @@ style falls back to a `note` admonition style. Use the ``:open:`` option as a flag to expand the admonition by default. -.. result:: +.. rst-example:: .. details:: Closed by default :class: help @@ -150,14 +150,14 @@ The admonition's title can be removed if the ``md-admonition`` directive is not any arguments. Because the ``md-admonition`` directive is an adaptation of the generic ``admonition`` directive, the ``class`` option is still respected. -.. result:: +.. rst-example:: .. md-admonition:: :class: error This example uses the styling of the ``error`` admonition -.. result:: +.. rst-example:: .. md-admonition:: Using a title :class: help @@ -183,7 +183,7 @@ folder and add the new CSS to an additional style sheet. .. md-tab-item:: rST code - .. result:: Pied Piper Example + .. rst-example:: Pied Piper Example :output-prefix: .. admonition:: Pied Piper diff --git a/docs/content_tabs.rst b/docs/content_tabs.rst index 469760741..140b7e236 100644 --- a/docs/content_tabs.rst +++ b/docs/content_tabs.rst @@ -42,7 +42,7 @@ the sphinx-immaterial theme provides its own directives to make use of content t This directive supports ``:class:`` and ``:name:`` options to use custom CSS classes and reference links (respectively). - .. result:: ``md-tab-set`` Example + .. rst-example:: ``md-tab-set`` Example .. md-tab-set:: :class: custom-tab-set-style @@ -84,7 +84,7 @@ the sphinx-immaterial theme provides its own directives to make use of content t Use the ``:class:`` option to optionally provide custom CSS classes to the tab's content (not the tab's label). - .. result:: ``md-tab-item`` Example + .. rst-example:: ``md-tab-item`` Example .. md-tab-set:: diff --git a/docs/demo_api.rst b/docs/demo_api.rst index 3ae3dd31c..6248d1875 100644 --- a/docs/demo_api.rst +++ b/docs/demo_api.rst @@ -7,7 +7,7 @@ sample API documentation and generated content :mod:`test_py_module` ===================== -.. result:: autodoc example +.. rst-example:: autodoc example .. automodule:: test_py_module.test :members: @@ -17,13 +17,13 @@ sample API documentation and generated content C++ API ======= -.. result:: +.. rst-example:: .. cpp:type:: MyType Some type -.. result:: +.. rst-example:: .. c:macro:: DEFAULT_LENGTH @@ -31,31 +31,31 @@ C++ API Some function type thing -.. result:: +.. rst-example:: .. cpp:class:: template std::array Some cpp class -.. result:: +.. rst-example:: .. cpp:member:: float Sphinx::version The description of `Sphinx::version`. -.. result:: +.. rst-example:: .. cpp:var:: int version The description of version. -.. result:: +.. rst-example:: .. cpp:type:: std::vector List The description of List type. -.. result:: +.. rst-example:: .. cpp:enum:: MyEnum @@ -83,18 +83,18 @@ JavaScript API .. js:module:: module_a.submodule -.. result:: +.. rst-example:: * Link to :js:class:`ModTopLevel` -.. result:: +.. rst-example:: .. js:class:: ModTopLevel * Link to :js:meth:`mod_child_1` * Link to :js:meth:`ModTopLevel.mod_child_1` -.. result:: +.. rst-example:: .. js:method:: ModTopLevel.mod_child_1 @@ -104,13 +104,13 @@ JavaScript API * Link to :js:meth:`module_a.submodule.ModTopLevel.mod_child_1` -.. result:: +.. rst-example:: * Link to :js:class:`ModTopLevel` .. js:module:: module_b.submodule -.. result:: +.. rst-example:: .. js:class:: ModNested @@ -135,7 +135,7 @@ JavaScript API Generated Index =============== -.. result:: +.. rst-example:: A generated index (:ref:`genindex`) is part of the Sphinx build process, unless `html_use_index` is set to `False`. @@ -150,7 +150,7 @@ Generated Index Data ==== -.. result:: +.. rst-example:: .. data:: Data_item_1 Data_item_2 diff --git a/docs/keys.rst b/docs/keys.rst index 71c2d849b..40fbaf713 100644 --- a/docs/keys.rst +++ b/docs/keys.rst @@ -64,7 +64,7 @@ Keys extension role The value of this role is interpreted as a keyboard key name. Each role invocation can describe multiple keys pressed simultaneously using the `keys_separator`. - .. result:: + .. rst-example:: :keys:`ctrl+alt+tab` @@ -143,7 +143,7 @@ project's conf.py file. In our case, ``my-special-key`` to fetch the display text from `keys_map`. - .. result:: + .. rst-example:: :keys:`my-special-key` + :keys:`git` = :keys:`git+my-special-key` @@ -153,6 +153,6 @@ project's conf.py file. ``My Special Key`` ignores the `keys_map` but still uses the ``key-my-special-key`` CSS class. - .. result:: + .. rst-example:: :keys:`My Special Key` + :keys:`Git` = :keys:`Git+My Special Key` diff --git a/docs/mermaid_diagrams.rst b/docs/mermaid_diagrams.rst index 0b1107831..599244f70 100644 --- a/docs/mermaid_diagrams.rst +++ b/docs/mermaid_diagrams.rst @@ -48,7 +48,7 @@ directive that exposes the underlying implementation in mkdocs-material theme. While all `mermaid.js`_ features should work out-of-the-box, this theme will currently only adjust the fonts and colors for the following types of diagrams: - .. result:: References linking directly to a diagram's ``:name:`` + .. rst-example:: References linking directly to a diagram's ``:name:`` - `flowcharts`_ - `sequence diagrams ` @@ -59,7 +59,7 @@ directive that exposes the underlying implementation in mkdocs-material theme. Using flowcharts ---------------- -.. result:: +.. rst-example:: .. md-mermaid:: :name: flowcharts @@ -74,7 +74,7 @@ Using flowcharts Using sequence diagrams ----------------------- -.. result:: +.. rst-example:: .. md-mermaid:: :name: sequence-diagrams @@ -92,7 +92,7 @@ Using sequence diagrams Using state diagrams -------------------- -.. result:: +.. rst-example:: .. md-mermaid:: :name: state-diagrams @@ -113,7 +113,7 @@ Using state diagrams Using class diagrams -------------------- -.. result:: +.. rst-example:: .. md-mermaid:: :name: class-diagrams @@ -148,7 +148,7 @@ Using class diagrams Using entity-relationship diagrams ---------------------------------- -.. result:: +.. rst-example:: .. md-mermaid:: :name: entity-relationship-diagrams diff --git a/docs/specimen.rst b/docs/specimen.rst index 8d51c9e2b..d5515527e 100644 --- a/docs/specimen.rst +++ b/docs/specimen.rst @@ -373,14 +373,14 @@ Images Default Alignment ~~~~~~~~~~~~~~~~~ -.. result:: +.. rst-example:: .. image:: desert-flower.jpg :alt: Default image Center Alignment ~~~~~~~~~~~~~~~~ -.. result:: +.. rst-example:: .. image:: desert-flower.jpg :alt: Centered Image, 80% scale @@ -389,7 +389,7 @@ Center Alignment Right Alignment ~~~~~~~~~~~~~~~ -.. result:: +.. rst-example:: .. image:: desert-flower.jpg :alt: Right Image, 60% scale diff --git a/docs/task_lists.rst b/docs/task_lists.rst index 903967408..6d7dcc144 100644 --- a/docs/task_lists.rst +++ b/docs/task_lists.rst @@ -87,7 +87,7 @@ Config variables .. md-tab-item:: rST code - .. result:: Custom icons scoped to immediate list only (not child lists) + .. rst-example:: Custom icons scoped to immediate list only (not child lists) .. task-list:: :class: custom-task-list-style @@ -136,7 +136,7 @@ Task List Example The following `task-list` example demonstrates nested `task-list`. Notice that indentation is important with reStructuredText lists. -.. result:: A feature spanning ``task-list`` example +.. rst-example:: A feature spanning ``task-list`` example .. task-list:: :name: task_list_example diff --git a/sphinx_immaterial/theme_result.py b/sphinx_immaterial/theme_result.py index cbe294fa8..b1f41eb24 100644 --- a/sphinx_immaterial/theme_result.py +++ b/sphinx_immaterial/theme_result.py @@ -50,4 +50,4 @@ def run(self): def setup(app): - app.add_directive("result", ResultsDirective) + app.add_directive("rst-example", ResultsDirective) From ba707ef7ded142a1b2eda8d9c303936b43047a16 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Mon, 11 Apr 2022 18:35:31 -0700 Subject: [PATCH 20/31] use snake casing for docutils node --- sphinx_immaterial/task_lists.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sphinx_immaterial/task_lists.py b/sphinx_immaterial/task_lists.py index c4e46737d..409c25984 100644 --- a/sphinx_immaterial/task_lists.py +++ b/sphinx_immaterial/task_lists.py @@ -26,7 +26,7 @@ def depart_checkbox_label(self: HTMLTranslator, node: nodes.Node): self.body.append("") -class checkboxLabel(nodes.container): +class checkbox_label(nodes.container): pass @@ -76,7 +76,7 @@ def first_matching(obj, cls_t): li_[first_para][first_text] = li_[first_para][ first_text ].lstrip("[ ] ") - checkbox = checkboxLabel( + checkbox = checkbox_label( "", custom=custom, disabled=not clickable, @@ -90,6 +90,6 @@ def first_matching(obj, cls_t): def setup(app: Sphinx): """Setup the extension.""" app.add_directive("task-list", TaskListDirective) - app.add_node(checkboxLabel, html=(visit_checkbox_label, depart_checkbox_label)) + app.add_node(checkbox_label, html=(visit_checkbox_label, depart_checkbox_label)) app.add_config_value("custom_checkbox", False, rebuild="html", types=bool) app.add_config_value("clickable_checkbox", False, rebuild="html", types=bool) From 40a0e9e84722cfbf20821ba220d7185f49a954bd Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Mon, 11 Apr 2022 20:37:23 -0700 Subject: [PATCH 21/31] move a margin reset to typeset.scss --- src/assets/stylesheets/main/_api.scss | 6 ------ src/assets/stylesheets/main/_typeset.scss | 8 ++++++++ 2 files changed, 8 insertions(+), 6 deletions(-) diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index 99210b544..5f42d8703 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -240,9 +240,3 @@ table.longtable.docutils.data.align-default { } } } - -// a rule to reset margin for code-blocks with a caption -.md-typeset .code-block-caption + .notranslate pre, -.md-typeset .code-block-caption + .notranslate .highlighttable { - margin-top: 0; -} diff --git a/src/assets/stylesheets/main/_typeset.scss b/src/assets/stylesheets/main/_typeset.scss index 336985544..af5bdf822 100644 --- a/src/assets/stylesheets/main/_typeset.scss +++ b/src/assets/stylesheets/main/_typeset.scss @@ -256,6 +256,14 @@ kbd { } } + // sphinx-immaterial: reset margin for code-blocks with a caption + .code-block-caption + .notranslate { + pre, + .highlighttable { + margin-top: 0; + } + } + // Keyboard key kbd { display: inline-block; From bb6ed636fb0f9f2c449fa6716bec9d014fb29192 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 12 Apr 2022 19:41:37 -0700 Subject: [PATCH 22/31] review changes to kbd_keys.py --- sphinx_immaterial/kbd_keys.py | 88 +++++++++++------------------------ 1 file changed, 26 insertions(+), 62 deletions(-) diff --git a/sphinx_immaterial/kbd_keys.py b/sphinx_immaterial/kbd_keys.py index b9b31547a..b2c60bdb5 100644 --- a/sphinx_immaterial/kbd_keys.py +++ b/sphinx_immaterial/kbd_keys.py @@ -18,87 +18,52 @@ keys_db = None -class spanNode(nodes.container): +class kbd_node(nodes.TextElement): pass -def visit_span(self: HTMLTranslator, node: spanNode): - self.body.append("" + node["text"]) - else: - self.body.append(">") - - -def depart_span(self: HTMLTranslator, node: spanNode): - self.body.append("") - - -class kbdNode(nodes.container): - pass - - -def visit_kbd(self, node): - self.body.append( - '' + node["text"]) - else: - self.body.append('">') - - -def depart_kbd(self, node): - self.body.append("") - - -def keys_role( - role, rawtext, text, lineno, inliner, options={}, content=[] -) -> Tuple[List[nodes.Node], List[str]]: - keys = text.split(KEYS_OPTS["keys_sep"]) - keys_div = spanNode("", classes=[KEYS_OPTS["keys_class"]]) - if KEYS_OPTS["keys_strict"]: - keys_div = kbdNode("", classes=[KEYS_OPTS["keys_class"]]) - keys_out = [] +def visit_kbd(self: HTMLTranslator, node: kbd_node): + tag = "kbd" if self.builder.config["keys_strict"] else "span" + self.body.append(f'<{tag} class="' + f'{self.builder.config["keys_class"]}"') + keys = node.rawsource.split(self.builder.config["keys_separator"]) def map_filter(key: str) -> Tuple[str, str]: display = key.title() cls = key.replace("_", "-").replace(" ", "-").lower() - if key in KEYS_OPTS["keys_map"].keys(): - display = KEYS_OPTS["keys_map"][key] + if key in self.builder.config["keys_map"].keys(): + display = self.builder.config["keys_map"][key] if keys_db is not None: if key in keys_db.aliases: display = keys_db.keymap[keys_db.aliases[key]] cls = keys_db.aliases[key] return (cls, display) + keys_out = ">" for i, key in enumerate(keys): key_cls, key_display = map_filter(key.strip().lower()) - keys_key = kbdNode("", classes=["key-" + key_cls]) - keys_key["text"] = key_display - keys_out.append(keys_key) + keys_out += f'{key_display}' if i + 1 != len(keys): - keys_sep = spanNode("", classes=[]) - keys_sep["text"] = KEYS_OPTS["keys_sep"] - keys_out.append(keys_sep) - keys_div += keys_out - return [keys_div], [] + keys_out += f'{self.builder.config["keys_separator"]}' + self.body.append(keys_out) + + +def depart_kbd(self, node): + tag = "kbd" if self.builder.config["keys_strict"] else "span" + self.body.append(f"") -KEYS_OPTS = {"keys_map": ({} if keys_db is None else keys_db.keymap.copy())} +def keys_role( + role, rawtext, text, lineno, inliner, options={}, content=[] +) -> Tuple[List[nodes.Node], List[str]]: + keys_div = kbd_node(text) + return [keys_div], [] def _config_inited(app: Sphinx, config: Config) -> None: - """Set defaults for `key` role options based on conf.py vars.""" - KEYS_OPTS["keys_class"] = app.config["keys_class"] - KEYS_OPTS["keys_sep"] = app.config["keys_separator"] - KEYS_OPTS["keys_strict"] = app.config["keys_strict"] - if app.config["keys_map"].keys(): - KEYS_OPTS["keys_map"].update(**app.config["keys_map"]) + """Merge default `keys_db.keymap` with user-specified `keys_map` role option.""" + if keys_db is not None and app.config["keys_map"].keys(): + keys_db.keymap.update(**app.config["keys_map"]) + app.config["keys_map"] = keys_db.keymap def setup(app: Sphinx): @@ -108,5 +73,4 @@ def setup(app: Sphinx): app.add_config_value("keys_map", {}, rebuild=True, types=dict) app.add_role("keys", keys_role) app.connect("config-inited", _config_inited) - app.add_node(spanNode, html=(visit_span, depart_span)) - app.add_node(kbdNode, html=(visit_kbd, depart_kbd)) + app.add_node(kbd_node, html=(visit_kbd, depart_kbd)) From a33bd45991b5847a52a8829858a82b4cebabc385 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 12 Apr 2022 20:29:34 -0700 Subject: [PATCH 23/31] use plain text for keys role in latex --- sphinx_immaterial/kbd_keys.py | 46 ++++++++++++++++++++++++----------- 1 file changed, 32 insertions(+), 14 deletions(-) diff --git a/sphinx_immaterial/kbd_keys.py b/sphinx_immaterial/kbd_keys.py index b2c60bdb5..6b35e0ca4 100644 --- a/sphinx_immaterial/kbd_keys.py +++ b/sphinx_immaterial/kbd_keys.py @@ -22,26 +22,27 @@ class kbd_node(nodes.TextElement): pass +def map_filter(key: str, user_map: dict) -> Tuple[str, str]: + display = key.title() + cls = key.replace("_", "-").replace(" ", "-").lower() + if key in user_map.keys(): + display = user_map[key] + if keys_db is not None: + if key in keys_db.aliases: + display = keys_db.keymap[keys_db.aliases[key]] + cls = keys_db.aliases[key] + return (cls, display) + + def visit_kbd(self: HTMLTranslator, node: kbd_node): tag = "kbd" if self.builder.config["keys_strict"] else "span" self.body.append(f'<{tag} class="' + f'{self.builder.config["keys_class"]}"') keys = node.rawsource.split(self.builder.config["keys_separator"]) - def map_filter(key: str) -> Tuple[str, str]: - display = key.title() - cls = key.replace("_", "-").replace(" ", "-").lower() - if key in self.builder.config["keys_map"].keys(): - display = self.builder.config["keys_map"][key] - if keys_db is not None: - if key in keys_db.aliases: - display = keys_db.keymap[keys_db.aliases[key]] - cls = keys_db.aliases[key] - return (cls, display) - keys_out = ">" for i, key in enumerate(keys): - key_cls, key_display = map_filter(key.strip().lower()) - keys_out += f'{key_display}' + cls, text = map_filter(key.strip().lower(), self.builder.config["keys_map"]) + keys_out += f'{text}' if i + 1 != len(keys): keys_out += f'{self.builder.config["keys_separator"]}' self.body.append(keys_out) @@ -52,6 +53,19 @@ def depart_kbd(self, node): self.body.append(f"") +def visit_kbd_latex(self, node): + keys = node.rawsource.split(self.builder.config["keys_separator"]) + for i, key in enumerate(keys): + _, text = map_filter(key.strip().lower(), self.builder.config["keys_map"]) + self.body.append(text) + if i + 1 < len(keys): + self.body.append(f' {self.builder.config["keys_separator"]} ') + + +def depart_kbd_latex(self, node): + pass + + def keys_role( role, rawtext, text, lineno, inliner, options={}, content=[] ) -> Tuple[List[nodes.Node], List[str]]: @@ -73,4 +87,8 @@ def setup(app: Sphinx): app.add_config_value("keys_map", {}, rebuild=True, types=dict) app.add_role("keys", keys_role) app.connect("config-inited", _config_inited) - app.add_node(kbd_node, html=(visit_kbd, depart_kbd)) + app.add_node( + kbd_node, + html=(visit_kbd, depart_kbd), + latex=(visit_kbd_latex, depart_kbd_latex), + ) From 67e7b64da6f36a9924ac123a6b741da4ad810df2 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 12 Apr 2022 21:33:12 -0700 Subject: [PATCH 24/31] simplfy example CSS for custom task-list --- docs/_static/extra_css.css | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/_static/extra_css.css b/docs/_static/extra_css.css index f79ccee51..bfb5ad333 100644 --- a/docs/_static/extra_css.css +++ b/docs/_static/extra_css.css @@ -42,7 +42,7 @@ /* **************************** custom-task-list style rules *************************** */ /* style for the unchecked checkboxes */ -.custom-task-list-style>ul>.task-list-item>.task-list-control>.task-list-indicator::before { +.custom-task-list-style > ul > li > label .task-list-indicator::before { -webkit-mask-image: var(--md-admonition-icon--failure); mask-image: var(--md-admonition-icon--failure); background-color: hsl(0, 72%, 55%); From 3f8a83f282f2dcb7bba4854bc61514676f76cd84 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Tue, 12 Apr 2022 21:44:49 -0700 Subject: [PATCH 25/31] move rst-result CSS to _highlight.scss --- src/assets/stylesheets/main/_sphinx.scss | 29 ----------- .../main/extensions/pymdownx/_highlight.scss | 49 +++++++++++++------ 2 files changed, 35 insertions(+), 43 deletions(-) diff --git a/src/assets/stylesheets/main/_sphinx.scss b/src/assets/stylesheets/main/_sphinx.scss index 7eb0fb232..c3b62a7e1 100644 --- a/src/assets/stylesheets/main/_sphinx.scss +++ b/src/assets/stylesheets/main/_sphinx.scss @@ -79,33 +79,4 @@ .rubric { font-weight: 700; } - - // theme-results directive special rules - .results .results-prefix { - margin-top: -1em; - padding: px2em(9px, 13.6px) px2em(16px, 13.6px); - font-weight: 700; - font-size: px2em(13.6px); - background-color: var(--md-code-bg-color); - } - - :is(.highlight, .highlighttable, .literal-block-wrapper), - div[class^="highlight-"], - .results-prefix { - + .result { - margin-top: -1em; - padding: 0 1em; - overflow: visible; - border: 0.05rem solid var(--md-code-bg-color); - border-top-width: 0.1rem; - border-bottom-right-radius: 0.1rem; - border-bottom-left-radius: 0.1rem; - } - } - - .results-prefix { - +.result { - margin-top: 0; - } - } } diff --git a/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss b/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss index de8ecf923..9959fb3d8 100644 --- a/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss +++ b/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss @@ -322,22 +322,43 @@ } // Code block result container - :is(.highlight, .highlighttable) + .result { - margin-top: calc(-1em + #{px2em(-2px)}); - padding: 0 px2em(16px); - overflow: visible; - border: px2rem(1px) solid var(--md-code-bg-color); - border-top-width: px2rem(2px); - border-bottom-right-radius: px2rem(2px); - border-bottom-left-radius: px2rem(2px); - - // Clearfix, because we can't use overflow: auto - &::after { - display: block; - clear: both; - content: ""; + // sphinx-immaterial: altered to support + // 1. docutils classes (.literal-block-wrapper, div[class^="highlight-"]) + // 2. rst-result directive's output-prefix (.results-prefix) + :is(.highlight, .highlighttable, .literal-block-wrapper), + div[class^="highlight-"], + .results-prefix { + + .result { + margin-top: calc(-1em + #{px2em(-2px)}); + padding: 0 px2em(16px); + overflow: visible; + border: px2rem(1px) solid var(--md-code-bg-color); + border-top-width: px2rem(2px); + border-bottom-right-radius: px2rem(2px); + border-bottom-left-radius: px2rem(2px); + + // Clearfix, because we can't use overflow: auto + &::after { + display: block; + clear: both; + content: ""; + } } } + + // sphinx-immaterial: reset margin for rst-result directive's output-prefix + .results .results-prefix + .result { + margin-top: 0; + } + + // sphinx-immaterial: use modified style from span.filename (see above) + .results .results-prefix { + margin-top: -1em; + padding: px2em(9px, 13.6px) px2em(16px, 13.6px); + font-weight: 700; + font-size: px2em(13.6px); + background-color: var(--md-code-bg-color); + } } // ---------------------------------------------------------------------------- From 10d393114eec53bf68ad26b9f1d45ccdf2d66c41 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Thu, 14 Apr 2022 04:47:53 -0700 Subject: [PATCH 26/31] wrap each param in span & style said span --- sphinx_immaterial/apidoc_formatting.py | 8 ++++++++ src/assets/stylesheets/main/_api.scss | 24 +++--------------------- 2 files changed, 11 insertions(+), 21 deletions(-) diff --git a/sphinx_immaterial/apidoc_formatting.py b/sphinx_immaterial/apidoc_formatting.py index f0688e698..5c7db156a 100644 --- a/sphinx_immaterial/apidoc_formatting.py +++ b/sphinx_immaterial/apidoc_formatting.py @@ -167,6 +167,14 @@ def depart_desc_parameterlist( _, close_paren = node.get("parens", ("(", ")")) self.body[-1] = self.body[-1].replace(")", close_paren) + def visit_desc_parameter(self, node: sphinx.addnodes.desc_parameter) -> None: + self.body.append('') + super().visit_desc_parameter(node) + + def depart_desc_parameter(self, node: sphinx.addnodes.desc_parameter) -> None: + super().depart_desc_parameter(node) + self.body.append("") + def depart_field_name(self, node: docutils.nodes.Element) -> None: self.add_permalink_ref(node, _("Permalink to this headline")) super().depart_field_name(node) diff --git a/src/assets/stylesheets/main/_api.scss b/src/assets/stylesheets/main/_api.scss index 5f42d8703..03b027bed 100644 --- a/src/assets/stylesheets/main/_api.scss +++ b/src/assets/stylesheets/main/_api.scss @@ -67,29 +67,11 @@ $objinfo-icon-size: 16px; // Ensure each parameter starts on a new line and is indented. &.sig-wrap { - .sig-param, - .n { - + .kt, - + .k, - + .n:not(.sig-param) { - &::before { - white-space: pre; - // 5 spaces below result in 4 spaces of indent. - // For some reason one space is lost. - content: "\A "; - } - } - } - - .sig-param > .n:first-child::before { - white-space: pre; - content: "\A "; - } - - .sig-paren + span { - // Ensure the first paren ends the line + .sig-param-decl { &::before { white-space: pre; + // 5 spaces below result in 4 spaces of indent. + // For some reason one space is lost. content: "\A "; } } From f45ac1a2dfac08aae6104288a7642166e6a82397 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Sat, 16 Apr 2022 23:42:35 -0700 Subject: [PATCH 27/31] [no ci] move comment to proper location --- sphinx_immaterial/apidoc_formatting.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sphinx_immaterial/apidoc_formatting.py b/sphinx_immaterial/apidoc_formatting.py index 5c7db156a..a169b2624 100644 --- a/sphinx_immaterial/apidoc_formatting.py +++ b/sphinx_immaterial/apidoc_formatting.py @@ -134,7 +134,6 @@ def visit_desc(self, node: sphinx.addnodes.desc) -> None: # Augment the list of classes with `objdesc` to make it easier to # style these without resorting to hacks. - # add highlight to invoke syntax highlighting in CSS node["classes"].append("objdesc") super().visit_desc(node) @@ -148,6 +147,7 @@ def depart_desc_type(self, node: sphinx.addnodes.desc_type) -> None: def visit_desc_signature(self, node: sphinx.addnodes.desc_signature) -> None: node_text = node.astext() + # add highlight to invoke syntax highlighting in CSS node["classes"].append("highlight") if len(node_text) > SIGNATURE_WRAP_LENGTH: node["classes"].append("sig-wrap") From ceef35f7f83c76d2b4b1917725885c6f666b6494 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Sun, 17 Apr 2022 00:06:09 -0700 Subject: [PATCH 28/31] condensed selectors = less deviation from upstream --- .../main/extensions/pymdownx/_highlight.scss | 32 ++++++++----------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss b/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss index 9959fb3d8..0ae683473 100644 --- a/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss +++ b/src/assets/stylesheets/main/extensions/pymdownx/_highlight.scss @@ -325,24 +325,20 @@ // sphinx-immaterial: altered to support // 1. docutils classes (.literal-block-wrapper, div[class^="highlight-"]) // 2. rst-result directive's output-prefix (.results-prefix) - :is(.highlight, .highlighttable, .literal-block-wrapper), - div[class^="highlight-"], - .results-prefix { - + .result { - margin-top: calc(-1em + #{px2em(-2px)}); - padding: 0 px2em(16px); - overflow: visible; - border: px2rem(1px) solid var(--md-code-bg-color); - border-top-width: px2rem(2px); - border-bottom-right-radius: px2rem(2px); - border-bottom-left-radius: px2rem(2px); - - // Clearfix, because we can't use overflow: auto - &::after { - display: block; - clear: both; - content: ""; - } + :is(.highlight, .highlighttable, .literal-block-wrapper, div[class^="highlight-"], .results-prefix) + .result { + margin-top: calc(-1em + #{px2em(-2px)}); + padding: 0 px2em(16px); + overflow: visible; + border: px2rem(1px) solid var(--md-code-bg-color); + border-top-width: px2rem(2px); + border-bottom-right-radius: px2rem(2px); + border-bottom-left-radius: px2rem(2px); + + // Clearfix, because we can't use overflow: auto + &::after { + display: block; + clear: both; + content: ""; } } From 00c0f1c682c5e20e59e027b208201e241fd611fe Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Sun, 17 Apr 2022 00:26:46 -0700 Subject: [PATCH 29/31] set autocrlf to input --- .gitattributes | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.gitattributes b/.gitattributes index ec8970737..db29bf5c9 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,5 +1,5 @@ -# Set the default behavior, in case people don't have core.autocrlf set. -* text=auto +# Set the default behavior, in case people have core.autocrlf set differently. +* text=input # Explicitly declare text files you want to always be normalized and converted # to native line endings on checkout. From 3231096d443f38d03c710116b76debe590a945c0 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Sun, 17 Apr 2022 01:46:03 -0700 Subject: [PATCH 30/31] try overriding git global config for this repo --- .gitattributes | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/.gitattributes b/.gitattributes index db29bf5c9..2ffc478f8 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,8 +1,10 @@ -# Set the default behavior, in case people have core.autocrlf set differently. -* text=input +# We need to make sure that the remote and workspace line endings all use LF due to +# linting and other reasons. +[core] + # Set core.autocrlf to false in case people have this set differently. + # If this is set to 'true' or 'input', then it overrides the eol option. + autocrlf=false -# Explicitly declare text files you want to always be normalized and converted -# to native line endings on checkout. -*.py text eol=lf -*.rst text eol=lf -*.scss text eol=lf \ No newline at end of file + # This setting forces Git to normalize line endings to LF on checkin and + # prevents conversion to CRLF when the file is checked out. + eol=lf From 727abf5bf4d700c63db95be92cff50fb398cf119 Mon Sep 17 00:00:00 2001 From: 2bndy5 <2bndy5@gmail.com> Date: Sun, 17 Apr 2022 02:17:09 -0700 Subject: [PATCH 31/31] override config for all files (not by core config) --- .gitattributes | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/.gitattributes b/.gitattributes index 2ffc478f8..813e4309d 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,10 +1,10 @@ # We need to make sure that the remote and workspace line endings all use LF due to # linting and other reasons. -[core] - # Set core.autocrlf to false in case people have this set differently. - # If this is set to 'true' or 'input', then it overrides the eol option. - autocrlf=false - # This setting forces Git to normalize line endings to LF on checkin and - # prevents conversion to CRLF when the file is checked out. - eol=lf +# Set core.autocrlf to false in case people have this set differently. +# If this is set to 'true' or 'input', then it overrides the eol option. +* text autocrlf=false + +# This setting forces Git to normalize line endings to LF on checkin and +# prevents conversion to CRLF when the file is checked out. +* text eol=lf