I also noticed that a tab item in which the toc entry is just RST links will forward to only the first link in the list. This is exemplified in my CirPy_nRF24 docs' "other links" tab.

RST source code:

.. toctree::
    :caption: Other Links
    :hidden:

    Download <https://github.com/2bndy5/CircuitPython_nRF24L01/releases/latest>
    CircuitPython Reference Documentation <https://circuitpython.readthedocs.io>
    CircuitPython Support Forum <https://forums.adafruit.com/viewforum.php?f=60>
    Discord Chat <https://adafru.it/discord>
    Adafruit Learning System <https://learn.adafruit.com>
    Adafruit Blog <https://blog.adafruit.com>
    Adafruit Store <https://www.adafruit.com>

We should probably put a note in the docs that this convention cannot be supported with navigation tabs. Although it is supported in the side navigation menu.

Originally posted by @2bndy5 in #31 (comment)

Well, it looks like linked content tabs will remain an insiders feature only. Originally, I thought the feature would get included in the public releases when the upstream funding goal hit $5000+, but the linked tabs feature wasn't made public when that goal was recently met.

So, we have to implement linked tabs ourselves.

Implementation

I envision this as a :linked: option to the md-tab-item directive. This could be a flag (option accepts no value) or an option that expects an identifying string.

• Expecting a string value would align with sphinx-design implementation and allow for linked tabs to have different labels.
• A flag might be easier from the user's perspective (relying on commonly shared tabs' labels), but that may be error prone. For example, case sensitivity or non-text elements in the linked tabs' labels.

I also noticed that tocdepth is not actually respected by nav_adapt.py, other than handling the special case of tocdepth == 0.

Originally posted by @jbms in #40 (comment)

I noticed after merging #60, the CSS styling of type hints (type annotations) has changed. I believe the issue comes from the changes in sphinx_immaterial/apidoc_formatting.py and/or src/assets/stylesheets/main/_api.scss.

It seems this change is where the type hint inherits the --md-typeset-a-color color.

Before:

After:

Before: 8c96b11

After: d874316

This isn't really a problem with this theme's synopsis feature.

I noticed that sphinx_utils.summarize_element_text() may yeild the wrong text because doxygen's XML tends to use different paragraph structure, and breathe simply attempts to output a node tree based on the doxygen XML output (1:1).

So, I'm suggesting a note about synopsis compatibility with other sphinx extensions that don't use nodes.paragraph exactly like sphinx/docutils does.

Example

expected results

useing the RST code

    .. cpp:function:: RF24::RF24(uint32_t _spi_speed=RF24_SPI_SPEED)

        :param _spi_speed: The SPI speed in Hz ie: 1000000 == 1Mhz

            - Users can specify default SPI speed by modifying :c:macro:`RF24_SPI_SPEED` in :file:`RF24_config.h`
        
              - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
              - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
              - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

<definition>
    <paragraph>
        <inline translatable="True">
            The SPI speed in Hz ie: 1000000 == 1Mhz
            <bullet_list>
                <list_item>
                    <paragraph>
                        Users can specify default SPI speed by modifying
                        <pending_xref refdomain="std" refexplicit="True" refid="RF24__config_8h_1a63ef6fd21b0b83db10e95c0da126d1e2" reftarget="RF24__config_8h_1a63ef6fd21b0b83db10e95c0da126d1e2" reftype="ref">
                            RF24_SPI_SPEED
                         in
                        <pending_xref refdomain="std" refexplicit="True" refid="RF24__config_8h" reftarget="RF24__config_8h" reftype="ref">
                            RF24_config.h
                        <bullet_list>
                            <list_item>
                                <paragraph>
                                    For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
                            <list_item>
                                <paragraph>
                                    Older/Unsupported Arduino devices will use a default clock divider & settings configuration
                            <list_item>
                                <paragraph>
                                    For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

Resulting synopsis for the parameter:

RF24::RF24::RF24::_spi_speed (C++ function parameter) — The SPI speed in Hz ie: 1000000 == 1Mhz

unexpected results (using doxygen+breathe)

using the documented prototype in a header file:

    /**
     * @param _spi_speed The SPI speed in Hz ie: 1000000 == 1Mhz
     * - Users can specify default SPI speed by modifying @ref RF24_SPI_SPEED in @ref RF24_config.h
     *     - For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
     *     - Older/Unsupported Arduino devices will use a default clock divider & settings configuration
     *     - For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7
     */
    RF24(uint32_t _spi_speed = RF24_SPI_SPEED);

<definition>
    <paragraph>
        <inline translatable="True">
            <paragraph>
                The SPI speed in Hz ie: 1000000 == 1Mhz
            <bullet_list bullet="-">
                <list_item>
                    <paragraph>
                        Users can specify default SPI speed by modifying
                        <pending_xref cpp:parent_key="<sphinx.domains.cpp.LookupKey object at 0x000001D18B4A8CA0>" refdoc="classRF24" refdomain="c" refexplicit="False" reftarget="RF24_SPI_SPEED" reftype="macro" refwarn="False">
                            <literal classes="xref c c-macro">
                                RF24_SPI_SPEED
                         in
                        <literal classes="file" role="file">
                            RF24_config.h
                    <bullet_list bullet="-">
                        <list_item>
                            <paragraph>
                                For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS
                        <list_item>
                            <paragraph>
                                Older/Unsupported Arduino devices will use a default clock divider & settings configuration
                        <list_item>
                            <paragraph>
                                For Linux: The old way of setting SPI speeds using BCM2835 driver enums has been removed as of v1.3.7

Resulting synopsis for the parameter:

RF24::RF24::RF24::_spi_speed (C++ function parameter) — For Arduino, the default SPI speed will only be properly configured this way on devices supporting SPI TRANSACTIONS

There are 2 reasons why I think this would be useful.

1. If a documented API uses a lot of parameters, then the ToC gets very long and visually complex (despite the include_object_description_fields_in_toc config value).
2. When writing new documentation for API, it can be annoying to see a warning related to missing parameter descriptions.
   • I wouldn't do this myself, but some might consider a parameter's name/type as "self-descriptive enough." Thus, they would deliberately neglect adding parameter description(s).

The only objection I can think of is: If disabling cross-linked parameters, would it affect other C++ domain customization options, namely synopses?

I imagine that the option's name would be cpp_cross_link_parameters (defaults to True). This way it can be used independently from similar implementations for other domains (like Java or JS) - thinking optimistically about future additions 😃 .

Hey guys, really love what you've done here! I'm working to port over my open source project to this theme.

I know it's new and still being developed / polished. I was wondering if the navigation tabs feature from Material for Mkdocs is possible here with Sphinx?

At first, this felt like a personal style choice, but I've been adding custom CSS to all my docs that use this theme.

.linenos {
  background-color: var(--md-default-bg-color--light);
  margin-right: 0.5rem;
}

which transforms

into something a little more "legible" like so

I was wondering if this CSS change should be considered for this theme. Additionally, I kinda like how line numbers look in the mkdocs-material upstream

Sphinx and rST directives don't support HTML's details and summary tags, This theme has some css specifically for these tags which collides with other sphinx extensions that implement custom directives to enumerate the details & summary tags. Example using sphinx-panels (same result from using sphinx-design):

closed

open

Notice that the theme's css also assume any generic .. admonition:: is a .. note:: which impedes user-defined admonitions.

code to reproduce

Enable the extension in docs' conf.py

extensions = [
    "spinx_immaterial",
    "sphinx_panels",
]

Use the extension's introduced directives

.. dropdown:: Settings used in this documentation

    .. literalinclude:: ./conf.py
        :start-at: # -- HTML theme settings ------------------------------------------------
        :end-before: # ---- Other documentation options -------------------------

I have been looking into what the docs need and don't need. Much of what is there seems like it was copied from the sphinx-material theme's docs.

1. I don't think using numpy as an example API is a "simple" demonstration of the theme's capabilities. Furthermore, numpy-doc is not PEP517 compliant (as reported by pip), which complicates building the docs on different platforms.
2. Using to a Jupyter notebook also seems to further complicate what should be a "simple" demonstration (& even simpler docs build process). It requires pandoc (a 3rd party utility not available via pypi only) to convert the notebook into a sample doc.

My concern here is that if someone looks at the sphinx-immaterial docs, then finds API docs for an entirely separate library, they might get overwhelmed/confused.

ps - I'm under the impression that completed/revised docs are 1 of the last few things preventing a release (or pre-release) to pypi. I have been using a locally copied wheel to try this theme with readthedocs.org... Found another issue with compatibility there (it isn't a deal-breaking issue).

Due to the altered search system in this theme, any consecutive attempt to build docs results in the following error:

Exception occurred:
  File "/path/to/env/lib/python3.10/site-packages/sphinx/search/__init__.py", line 283, in load
    index2fn = frozen['docnames']
KeyError: 'docnames'

The current workaround is delete any previously built docs (specific to the project being worked on), then re-build the docs.

This affects IDE extensions designed to generate previews of documentation. I don't see a way to workaround this error in the vscode restructuredtext extension, so it would be nice to have this theme cooperate better with sphinx in this scenario.

Hello! It's great that you're taking this project and trying to generalize it!

I have an issue that I get this error:
GET http://localhost:63342/project_name/_build/html/_static/material.css
[HTTP/1.1 404 Not Found 16ms]

The resource from “http://localhost:63342/project_name/_build/html/_static/material.css” was blocked due to MIME type (“text/html”) mismatch (X-Content-Type-Options: nosniff).

Thanks :)

According to the new doc, users are instructed to

extensions = [
    # other extensions...
    "sphinx_immaterial.cppreferences",
]

But there is no module named sphinx_immaterial.cppreferences, rather it is the singular form (no trailing "s") sphinx_immaterial.cppreference.

I found that there is no copy button for longer code block which is 40 lines or more.

Expected behaviour

Actual behaviour

I use: Python 3.8.9, sphinx 4.4.0 and sphinx_material 0.4.0

I noticed that box drawing characters in sphinx-immaterial don't print with the same width. I tried several different fonts, even ones I know to "work" elsewhere, but can't seem to get uniform spacing. I've been digging into the CSS to try to determine what parameters could affect this (ligatures, etc). I was curious if anything in squidfunk/mkdocs-material#323 was related. Given my very limited HTML/CSS knowledge, this has proved difficult.

Any thoughts?

sphinx-immaterial

sphinx_rtd_theme

VS Code

I get the following error if I try to use sphinx-immaterial with a fresh sphinx project, created by sphinx-quickstart.

Extension error (sphinx_immaterial.nav_adapt):
Handler <function _html_page_context at 0x7f47a41e1c60> for event 'html-page-context' threw an exception (exception: 'NoneType' object has no attribute 'walk')

The reason is, that you need a toctree directive and at least one additional rst-file, which must be mentioned in the toctree directive.

So this does not work (index.rst):

Project
=======
Test me

This does also not work:

Project
=======
Test me

.. toctree::

but this works:

Project
=======
Test me

.. toctree::

   page.rst

The problematic code is inside nav_adapt.py:

def _get_mkdocs_toc(
    toc_node: docutils.nodes.Node, builder: sphinx.builders.Builder
) -> List[MkdocsNavEntry]:
    """Converts a docutils toc node into a mkdocs-format JSON toc."""
    visitor = _TocVisitor(sphinx.util.docutils.new_document(""), builder)
    toc_node.walk(visitor)
    return visitor._children

and there toc_node can be None for small documentation projects.

See discussion here:

#10 (comment)

This is a thread devoted to resolving merge conflicts from upstream mkdocs-material repo.

I just updated my local version of python to v3.10, rebuilt a new venv, and then tried to build some docs with this theme. The build failed saying

Running Sphinx v4.2.0
loading translations [en]... done

Exception occurred:
  File "C:\Users\ytreh\Documents\GitHub\venv\lib\site-packages\sphinx_immaterial\__init__.py", line 187, in <module>
    def dict_merge(*dicts: List[collections.Mapping]):
AttributeError: module 'collections' has no attribute 'Mapping'
The full traceback has been saved in C:\Users\ytreh\AppData\Local\Temp\sphinx-err-u29qe6xq.log, if you want to report the issue to the developers.

So, I took a look at where Mapping was really defined, and found it in CPython's Lib/typing.py

Mapping = _alias(collections.abc.Mapping, 2)

The code in this theme's __init__.py is

Solution

Change where Mapping is imported from, then remove the collections namespaces

from typing import List, Optional, Union, Type, Dict, Sequence, Tuple, Mapping
# ...
def dict_merge(*dicts: List[Mapping]): 
     """Recursively merges the members of one or more dicts.""" 
     result = dict() 
     for d in dicts: 
         for k, v in d.items(): 
             if (isinstance(v, Mapping) and k in result 

I haven't gone back to an older version of python to make sure this is backward compatible, but I imagine that this repo's build CI workflow (which uses py v3.9) would error out if there's any problems.

I went to play with the new features from #64 on my personal project and found this error when letting html_wrap_signatures_with_css be it's default value (which is None and interpreted as True).

Extension error (sphinx_immaterial.apidoc_formatting):
Handler <function _wrap_signatures at 0x000001AC357BACB0> for event 'object-description-transform' threw an exception (exception: argument of type 'NoneType' is not iterable)

The fix for this is to modify

    if isinstance(enabled, list) and domain not in enabled:

Just now discovering this because I assume only the list form of the option's value was last tested. Our docs is using

I keep running into a problem when using npm on windows to build the theme. It installs fine, but any docs built from the install doesn't properly link to the correct names of compiled CSS files in the installed theme's base.html template.

The generated docs try linking to files named main.css and pallete.css. However, they should be named main.<sha>.min.css and pallete.<sha>.min.css. I suspect it has something to do with the tools/build JS module.

Looking for JS advice again...

(venv) PS C:\path\to\sphinx-immaterial> npm -v
8.1.2

I have resorted to using WSL ubuntu bash (& related npm v8.1.2) to build a wheel and install to a Windows venv. Note that sphinx (& python in general) runs faster in Windows PS than it does in WSL terminal for some reason.

I am receiving no search queries in Google Analytics from my webpage using sphinx-immaterial. Full disclosure, I wasn't receiving them using sphinx_rtd_theme either. I was, however, able to see the search terms on the readthedocs.org Admin tab. I don't believe I get any search terms in the Admin tab with sphinx-immaterial.

My question still stands, though. It seems that it should be possible to receive Google Analytics search results as is discussed here with sphinx-immaterial.

I believe I'm configuring Google Analytics the correct way. And I can see that the JS is loaded and is emitting page references (which I can see in my GA dashboard).

html_theme_options = {
    "google_analytics": ["G-***********", "auto"],
}

However, the webpage is not emitting anything when search terms are typed or selected. I did some investigating and comparison with what the Material for Mkdocs webpage does. I found the Material for Mkdocs website does invoke analytics.js when searching and sphinx-immaterial does not, see below.

Thoughts on this? Can we add some JS to invoke the analytics.js after typing a search query (begin scrolling through results) or when clicking on a search result?

Material for Mkdocs

On https://squidfunk.github.io/mkdocs-material/, I typed the search term and nothing was emitted on the network. Once I scrolled down onto the first result, or clicked somewhere, the analytics.js was triggered (see the last line).

Examining the last packet, we see the ?q=a custom search query.

Google Analytics uses the q to parse the search result.

Sphinx Immaterial

I noticed no such ?q= emitted from my website https://galois.readthedocs.io/en/v0.0.25/index.html using sphinx-immaterial.

When arriving on a page, there is a analytics.js trigger just saying where we are.

However, after typing a search query, scrolling down through the results, and then clicking a page there is no additional analytics.js trigger with a ?q= included.

I noticed this a long time ago, but keep forgetting to file this issue.

An erroneous example can be seen in our hosted docs

I think the expected behavior is something that resembles a typical code-block but with cross-referencing links in certain parts of the code. I generally don't use the productionlist directive, but I figured I should say something.

The directive's docs are at the Sphinx docs

An expected behavior can be observed from the attached simple project (uses furo theme)
prod-list-proper.zip

I'm now getting warnings saying

GitHub\RF24\docs\sphinx\classRF24.rst:6: WARNING: Invalid parameter name: '_cepin'
GitHub\RF24\docs\sphinx\classRF24.rst:6: WARNING: Invalid parameter name: '_cspin'
GitHub\RF24\docs\sphinx\classRF24.rst:6: WARNING: Invalid parameter name: '_spi_speed'
GitHub\RF24\docs\sphinx\classRF24.rst:7: WARNING: Invalid parameter name: '_spi_speed'

The only commonality that these parameters have is that they're used as verbatim parameter names in multiple functions ( in overloaded c'tor and Arduino style begin()), and each name begins with a _. I might be misunderstanding the problem here, but I doubt that the _ is the culprit (removing the _ didn't prevent the warning).

EDITED: better diagnosis in first comment below

I'm guessing this warning should be saying "Non-unique parameter name" given that it is generated from

However, I would argue that re-using parameter names for multiple functions is an accepted practice. So, we shouldn't raise warnings about it (which would cause RTD builds to fail fast).

As of this morning, I get a failing build on RTD with this error. Upon investigation, the latest jinja2 (released today) does not support jinja2.Markup, see here. Instead, it states Markup should be imported from markupsafe.

I can submit a PR to either:

• Pin jinja < 3.1.0, or
• Add the markupsafe dependency (I believe it's already required by jinja2) and change the code to import Markup accordingly

Thoughts?

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/events.py", line 101, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx_immaterial/nav_adapt.py", line 410, in _html_page_context
    page_title = jinja2.Markup.escape(jinja2.Markup(context.get("title")).striptags())
AttributeError: module 'jinja2' has no attribute 'Markup'

The above exception was the direct cause of the following exception:

Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/cmd/build.py", line 284, in build_main
    app.build(args.force_all, filenames)
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/application.py", line 337, in build
    self.builder.build_update()
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 294, in build_update
    self.build(to_build,
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 358, in build
    self.write(docnames, list(updated_docnames), method)
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 532, in write
    self._write_serial(sorted(docnames))
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/__init__.py", line 542, in _write_serial
    self.write_doc(docname, doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 632, in write_doc
    self.handle_page(docname, ctx, event_arg=doctree)
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/builders/html/__init__.py", line 1033, in handle_page
    newtmpl = self.app.emit_firstresult('html-page-context', pagename,
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/application.py", line 464, in emit_firstresult
    return self.events.emit_firstresult(event, *args,
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/events.py", line 119, in emit_firstresult
    for result in self.emit(name, *args, allowed_exceptions=allowed_exceptions):
  File "/home/docs/checkouts/readthedocs.org/user_builds/galois/envs/312/lib/python3.8/site-packages/sphinx/events.py", line 109, in emit
    raise ExtensionError(__("Handler %r for event %r threw an exception") %
sphinx.errors.ExtensionError: Handler <function _html_page_context at 0x7f03eacd1a60> for event 'html-page-context' threw an exception (exception: module 'jinja2' has no attribute 'Markup')

Extension error (sphinx_immaterial.nav_adapt):
Handler <function _html_page_context at 0x7f03eacd1a60> for event 'html-page-context' threw an exception (exception: module 'jinja2' has no attribute 'Markup')

When I try to hide table of contents sidebars or navigation, it did not work. I add the following line in markdown files

---
hide:
  - navigation
  - toc
---

Is this the right method to hide table of contents sidebars or navigation? Thanks.

This seems worth mentioning in the docs' listed features.

Originally posted by @2bndy5 in #34 (comment)

Remind me to remove the bit from our docs about tabs only showing in large viewport.

Originally posted by @2bndy5 in #34 (comment)

I've been looking for what features work as expected to determine what config stuff should go into the docs. I happened across this code

but it seems to be unaltered from the original mkdocs-material theme's src/base.html.

Trying to minimize changes to base.html template

Now, I would like to pass the proper edit_url based on config context which is updated from html_page_context(), but I think I need to make the assumption that the document's source file is located in the docs folder. The source file's extension (.rst or any other supported suffix) can be fetched with the template's global variable page_source_suffix. Maybe there's a better way to do this, but this is what I have working so far.

--- sphinx_immaterial/__init__.py
+++ sphinx_immaterial/__init__.py
@@ -218,235 +218,241 @@
+    repo_url = theme_options.get("repo_url", None)
     context.update(
         config={
             "theme": theme_options,
             "site_url": theme_options.get("site_url"),
             "site_name": context["docstitle"],
-            "repo_name": theme_options.get("repo_url", None),
+            "repo_url": repo_url,
             "repo_name": theme_options.get("repo_name", None),
+            "edit_url": ""
+            if repo_url is None
+            else "/".join(
+                [repo_url.rstrip("/"), os.path.split(app.srcdir)[1], pagename]
+            ),
             "extra": {
                 "version": version_config,
                 "social": theme_options.get("social"),
                 "disqus": theme_options.get("disqus"),
                 "manifest": theme_options.get("pwa_manifest"),
             },
             "plugins": theme_options.get("plugins"),
             "google_analytics": theme_options.get("google_analytics"),
         },
         base_url=base_url,
    )

--- src/base.html
+++ src/base.html
@@ -298,306 +298,306 @@
-                {% if page.edit_url %}
+                {% if config.edit_url %}
                   <a
-                    href="{{ page.edit_url }}"
+                    href="{{ config.edit_url ~ page_source_suffix }}"
                     title="{{ lang.t('edit.link.title') }}"
                     class="md-content__button md-icon"
                   >
                     {% include ".icons/material/pencil.svg" %}
                   </a>
                 {% endif %}

You may have noticed that RTD has its own (probably more precise) mechanism that provides links to the document's source (see pictures in #7), but I figured I'd try to tackle this for completion (& people coming from mkdocs who've only ever used gh-pages). Here's a screenshot of the above changes' result:

A small observation, but...

I noticed that after the changes in #60 through #73 the API signature punctuation color has changed. It used to be var(--md-code-hl-punctuation-color), but now is overridden in some way.

This can be reproduced by adding any function to your docs that has a List[int], or some equivalent type hint. The [ are considered punctuation. Notice they were gray before but are pink now.

8c96b11

0e0dcc8

I'm getting ready to start exporting docygen XML to sphinx-immaterial (via breathe ext), and I noticed that function signatures that are wrapped to multiple lines are confusingly split between the parameter's datatype and name. Observe a test I made without doxygen/breathe (using standard sphinx cpp domain directives):

.. cpp:function:: const MyType Foo(const MyType bar, uint8_t baz, bool flag, uint16_t foobar, int32_t foobaz, unsigned long barbaz)

   Some function description.

I'm suspecting the fix should be placed in apidoc_formatting.py of this theme, but I still need to research more about how it detects the directive's domain.

I've just discovered this project, and love it (I have used sphinx-material for a while, but this gets much closer to mkdocs-material), thanks for maintaining it!

But, I can't work out how to provide extracopyright in a way that actually get's built into the rendered docs. I've put together a tiny demo here

https://github.com/duncanmmacleod/test-sphinx-immaterial

but nothing I put in my _templates/layout.html seems to have any effect. Is this possible?

I recently tried the version selector as the docs for this theme instruct, but it didn't work; the JSON file option nor the conf.py dict option made any difference or triggered any unusual build-time output. I know @jbms noted some changes to the version selector dopdown in his initial PR to the sphinx-material theme's repo

I changed the versions.json format to match the "mike" format supported by mkdocs-material.

So, I tried a json in the form that the mike plugin expects: still no joy.

At this point I think its just broken from a change in the HTML template's context variables. However, I'm actually having trouble finding the section of the template that integrates the version selector dropdown. I see the word "version" mentioned in the bottom of base.html about translations, but I have a feeling the mkdocs-material theme supports the mike plugin via added JS (which is where my expertise stops).

On a related note, I think I found the Sphinx alternative to the mkdocs' mike plugin: sphinxcontrib-versioning. It seems that this extension is the key ingredient to versioned docs on RTD as most of the sphinx themes' support it via the extension's html template API.

My initial intention was to try and have a doxygen rendered version and a sphinx/breathe rendered version of a project's docs I'm working on.

I'm in the process of converting my library over to this theme. Thanks for all the hard work creating this fork!!

I noticed when using navigation tabs that after clicking on the tab, the page /the-page.html is loaded with #first-section appended. So the URL is /the-page.html#first-section and not /the-page.html.

This can be observed on @2bndy5's website https://circuitpython-nrf24l01.readthedocs.io/en/latest/index.html.

When clicking "Network API Reference", the URL /topology.html#network-levels is loaded and not /topology.html.

Desired output:

PS: I noticed that when clicking on a navigation tab while currently on that tab (but halfway down the page), it loads the page correctly without the #first-section appended.

I'm ready to start pushing commits in prep for submitting a PR, but I'd like to verify 2 things first (so I don't have to walk some changes back).

1. Given the use of linting in JS, I'd like to add a .pylintrc for linting selective python sources. Doing so would also instigate the use of pylint in this repo's build.yml.
2. I tend to use black to format python sources in accordance with PEP8 standards. This would be applied to everything in the sphinx_immaterial folder.
   • I did find a requirement for black==19.10b0 in the requirements-dev.txt
3. I'm assuming that edits to the package-lock.json & package.json should not be committed. I didn't personally make any changes, but it looks like changes were made in the build process (or setting up nodejs for this project locally).

I raised this issue because I don't see a contributing guidelines in the repo root.

My intention is to have

look like

But it looks like the built theme only allows a limited set of options. So, how do I change the icon for admonitions? Usually I'd override the CSS styling to do this, but I don't see the compiled svg I want.

hello again! I've already brought this to your attention, but now I have something (a dummy repo) to actually share (as opsosed to building only locally and trying to describe symptoms with words).

In a new project (very early stages - execution is incomplete) I decided to try this theme in the docs because it has a very basic docs' config. However, I'm still not seeing the borders on tables. In this demonstation, the tables listing the functions/classes/modules of the python pkg is not styled correctly (or maybe its something I overlooked).

the docs are built in the repo's github actions workflow. The workflow log (if needed) can be observed also (seen here)

Notice I am using autosummary (with a customized template for better recursion) this time. More info about the docs config can be seen in the docs/config.py. Actually its a copy of the conf.py from my CirPy nRF24L01 lib's docs, but a lot of stuff is commented out.

ps - There are other discrepancies, but I figured 1 issue at a time (try the light and dark color palettes on a page with a code block in it).

Firstly, thanks for making this port available - it works and looks amazing!

It seems the newest version of sphinx (4.3) has a few API changes that leads to some breaks in this package. Namely:

• sphinx.search.IndexBuilder.get_objects() now returns a list of tuples rather than a dict, where the old dict key has now been included as the last item in the tuple.
• get_signature_prefix now returns a list of nodes rather than strings.

I'd be happy to contribute a PR with possible fixes if you'd like.

Are content tabs supported in this theme? I searched in the docs here, but didn't find any mention. Thanks!

I noticed that Sphinx roles are not applied in the navigation tab or content tab headings. Is there anything we can do about that? Is there a way to run a Sphinx role processor on the the titles or captions?

Content tabs

Here I tried to add an inline literal to a content tab heading. I also tried to add an octicon from the sphinx-design extension.
Potentially the octicon did get converted to a SVG but isn't displaying as such?

    Examples
    --------
    .. md-tab-set::

        .. md-tab-item:: n = 14

            Content one...

        .. md-tab-item:: ``n = 15``

            Content two...

        .. md-tab-item:: :octicon:`graph` Graphs

            Content three...

renders as

<div class="tabbed-labels docutils">
    <label class="tabbed-label" for="__tabbed_1_1">
        n = 14
    </label>
    <label class="tabbed-label" for="__tabbed_1_2">
        &lt;literal&gt;n = 15&lt;/literal&gt;
    </label>
    <label class="tabbed-label" for="__tabbed_1_3">
        &lt;raw format=”html” xml:space=”preserve”&gt;&lt;svg version=”1.1” width=”1.0em” height=”1.0em”
        class=”sd-octicon sd-octicon-graph” viewBox=”0 0 16 16” aria-hidden=”true”&gt;&lt;path fill-rule=”evenodd”
        d=”M1.5 1.75a.75.75 0 00-1.5 0v12.5c0 .414.336.75.75.75h14.5a.75.75 0 000-1.5H1.5V1.75zm14.28 2.53a.75.75 0
        00-1.06-1.06L10 7.94 7.53 5.47a.75.75 0 00-1.06 0L3.22 8.72a.75.75 0 001.06 1.06L7 7.06l2.47 2.47a.75.75 0
        001.06 0l5.25-5.25z”&gt;&lt;/path&gt;&lt;/svg&gt;&lt;/raw&gt; Graphs
    </label>
</div>

Navigation tabs

Here I tried to add an octicon to a navigation tab, but it didn't render as expected.

.. toctree::
   :caption: Getting Started
   :hidden:

   getting-started.rst

.. toctree::
   :caption: :octicon:`info` Basic Usage
   :hidden:

   basic-usage/galois-field-classes.rst
   basic-usage/compilation-modes.rst
   basic-usage/field-element-representation.rst
   basic-usage/array-creation.rst
   basic-usage/array-arithmetic.rst
   basic-usage/linear-algebra.rst
   basic-usage/poly-creation.rst
   basic-usage/poly-arithmetic.rst

.. toctree::
   :caption: Tutorials
   :hidden:

renders as

<ul class="md-tabs__list">
    <li class="md-tabs__item">
        <a href="getting-started.html" class="md-tabs__link">
            <span class="md-ellipsis">Getting Started</span>
        </a>
    </li>
    <li class="md-tabs__item">
        <a href="basic-usage/galois-field-classes.html" class="md-tabs__link">
            <span class="md-ellipsis">:<wbr>octicon:<wbr>`info` Basic Usage</span>
        </a>
    </li>
    <li class="md-tabs__item">
        <a href="tutorials/intro-to-prime-fields.html" class="md-tabs__link">
            <span class="md-ellipsis">Tutorials</span>
        </a>
    </li>
    ...
</ul>

I found that sometimes autosummary tables have very strange line wrapping. Below the functions are wrapped across three lines, even though the second column (function summary) hasn't yet reached the end of the table.

I'm willing to help resolve the issue (to the best of my ability). Can @jbms and/or @2bndy5 point me in the right direction? Is this an HTML decision of when to wrap text in each column?

Source file:

.. rubric:: Polynomial tests
.. autosummary::
   :toctree:

   is_monic
   is_irreducible
   is_primitive
   is_square_free

sphinx-immaterial (https://galois.readthedocs.io/en/latest/api/polys.html):

sphinx_rtd_theme (https://galois.readthedocs.io/en/v0.0.24/api/polys.html):

In my testing environment the Sphinx-Immaterial version of docs for our Python API has an issue with the right-side TOC panel: it doesn't scroll and is locked at approx. 1/3rd of the list of available Python methods. As I can see from the template docs in the Customization section, this index scrolls smoothly, when its elements are derived from headings.

For API documentation you can easily end up with a very long table of contents in the left and/or right side panels.

This results in two usability issues:

• The left TOC does not start out scrolled to have the current page in view, and the right TOC does not automatically keep the current section in view. That makes it challenging to understand the context of the current page/section. This feature is apparently implemented in the insiders-only version of mkdocs-material (squidfunk/mkdocs-material#2155).
• When scrolling the left or right TOC, if there are multiple levels of nesting, the ancestors of the current page/section may be scrolled out of view and not visible, which also makes it difficult to understand the context of the current page/section. This could be solved by making the section headers "sticky", so that the headers for each nesting level "collect" at the top of the TOC. An implementation of this is explained here: https://stackoverflow.com/a/55941740

I've made some mock up edits to better integrate into readthedocs hosted docs. All details can be observed at the issue I raised upstream. Unfortunately, the author has no intention to support RTD. I have 1 more use case to consider before I offer a PR here: when the user disables the nav side menu.

Thank you for your efforts on this beautiful theme.

I've met some trouble utilizing the "version selector" function:

1. when using the "version info" approach, the dropdown menu would always show the top choice(not current version):

2. the aliases won't work(return 404 on static site with nginx)

3. I've also tried the "version_json" approach, which has not effect at all. Tried to put the JSON file on over the place yet won't wokring:

   • same directory with conf.py
   • parent directory of conf.py
   • also as mention in docs:

     /versions.json
     /1.0/index.html
     /2.0/index.html
     

   • and all of above places together.

Can anyone please help me with how to achieve this function?

environment:

sphinx==4.4.0
sphinx-immaterial==0.3.1

I discovered that the changes in 1373cd7 cause issues with the left-side and right-side TOCs. Here is my repo built with two consecutive commits. The individual pages in a navigation tab TOC are combined into subheading of one page.

Also, FWIW, the page title on the left-side TOC is colored differently...

Here is a chunk of index.rst.

.. toctree::
   :caption: Getting Started
   :hidden:

   getting-started.rst

.. toctree::
   :caption: Basic Usage
   :hidden:

   basic-usage/galois-field-classes.rst
   basic-usage/compilation-modes.rst
   basic-usage/field-element-representation.rst
   basic-usage/array-creation.rst
   basic-usage/array-arithmetic.rst
   basic-usage/linear-algebra.rst
   basic-usage/poly-creation.rst
   basic-usage/poly-arithmetic.rst

.. toctree::
   :caption: Tutorials
   :hidden:

   tutorials/intro-to-prime-fields.rst
   tutorials/intro-to-extension-fields.rst

Built with e928b18

Built with 1373cd7

We have a weird error when we try to build our docs.
In most of our computers it works, in some it doesn't, I can't put my fingers on what is different between them.
Same Sphinx version (4.2.0), same Sphinx-immaterial version (0.2.0), similar Python version (3.7+), same code.

The error is:
Extension error (sphinx_immaterial.object_toc):
Handle <bound method _monkey_patch_toc_tree_process_doc.._patched_process_doc of <sphinx.environment.collectors.toctree.TocTreeCollector object at {id}>> for event 'doctree-read' threw an exception (exception: 'desc' object has no attribute '_traverse')

Thanks :)

Found another bug in the theme docs: in the New blocks section there's a description of a block responsible for substituting the default font. But it should read fonts instead of font – I realised that only after reading the code of the default layout.html file here in the repo:

When you use the following font block in the /_template/layout.html file that overrides defaults, nothing happens (the text font is still Roboto):

{# Import the theme's layout. #}
{% extends '!layout.html' %}

{% block font %}
        <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
        <link
          rel="stylesheet"
          href="https://fonts.googleapis.com/css?family=Lato:300,400,400i,700%7CRoboto+Mono&display=fallback"
        />
        <style>
          :root {
            --md-text-font-family: "Lato";
            --md-code-font-family: "Roboto Mono";
          }
        </style>
{% endblock %}

But this code works when you use {% block fonts %}.

Hi,
Recently I stumbled upon your project while looking for a Sphinx theme that would make our Python API docs (hosted on RTD) similarly looking to the general docs built in Material for MkDocs. A bit disappointed with the sphinx-material theme, I decided to test yours. Unfortunately, my first build attempts were unsuccessful:

writing output... [ 20%] galaxy.api Theme error: An error happened in rendering the page galaxy.api. Reason: TemplateNotFound('partials/languages/None.html')

I figured out it sth related to the language of the project, but in your docs there's nothing about the need to set the language in the conf.py file, otherwise the builder will fail (I guess it takes the None value and looks for the respective None.html file, which simply doesn't exist). In your conf.py file I found language = "en", put it into my conf.py and it worked like a charm.

You should either update the docs with some info regarding this parameter or implement an exception, which handles unspecified language by defaulting to EN, for instance.

Apart from that, it's a fantastic work! I'm impressed how smoothly you integrated the great Material for MkDocs theme with Sphinx.

Currently sphinx/rst do not provide a way that generates HTML that takes advantage of mkdocs-material's task lists (configured using a md extension again).

<ul class="task-list">
  <li class="task-list-item">
    <label class="task-list-control">
      <input type="checkbox" disabled="" checked="">
      <span class="task-list-indicator"></span>
    </label>
    Lorem ipsum dolor sit amet, consectetur adipiscing elit
  </li>
  <li class="task-list-item">
    <label class="task-list-control">
      <input type="checkbox" disabled="">
      <span class="task-list-indicator"></span>
    </label>
    Vestibulum convallis sit amet nisi a tincidunt
    <ul class="task-list">
      <li class="task-list-item">
        <label class="task-list-control">
          <input type="checkbox" disabled="" checked="">
          <span class="task-list-indicator"></span>
        </label>
        In hac habitasse platea dictumst
      </li>
      <li class="task-list-item">
        <label class="task-list-control">
          <input type="checkbox" disabled="" checked="">
          <span class="task-list-indicator"></span>
        </label>
        In scelerisque nibh non dolor mollis congue sed et metus
      </li>
      <li class="task-list-item">
        <label class="task-list-control">
          <input type="checkbox" disabled="">
          <span class="task-list-indicator"></span>
        </label>
        Praesent sed risus massa
      </li>
    </ul>
  </li>
  <li class="task-list-item">
    <label class="task-list-control">
      <input type="checkbox" disabled="">
      <span class="task-list-indicator"></span>
    </label>
    Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque
    </li>
</ul>

I'm not sure how popular the feature is, but I figured I'd discuss the implementation here before submitting a proposal.

About ideal syntax

I would prefer to be able to use the GitHub-flavored MD style of task lists (as used in upstream). This way users migrating from mkdocs to sphinx would be faced with less friction.

.. md-task-list::
    - [x] Lorem ipsum dolor sit amet, consectetur adipiscing elit
    - [ ] Vestibulum convallis sit amet nisi a tincidunt
        .. md-task-list::
            * [x] In hac habitasse platea dictumst
            * [x] In scelerisque nibh non dolor mollis congue sed et metus
            * [ ] Praesent sed risus massa
    - [ ] Aenean pretium efficitur erat, donec pharetra, ligula non scelerisque

There may be nothing stopping the user from implementing this on their own, but the styling from upstream (& thus this theme) is desirable.

About persistence

As noted in the upstream's docs, checkbox states aren't persistent. Although this could easily be done with a little extra JS from the user's end.