I have a TensorStore C++ autosummary also mostly implemented, although not yet released in the TensorStore repository. I would like to potentially incorporate it into this theme, but wanted to find out if that might be useful to anyone else. (If not, I'll just maintain it separately within TensorStore.)

It works similarly to the TensorStore Python autosummary extension, in that every entity is documented on a separate page.

At the top level, entities are organized into groups (like doxygen groups) and e.g. a .. cpp-apigen:: group directive is used to insert the summary of the members of a group.

Ideally, we would offer a Python API for defining custom admonitions, likely in the form of a config option to be specified in conf.py.

Currently it is possible to override the icons for existing admonitions using via the icon/admonition theme option, but to define a new admonition type, the user needs to:

1. Create a custom CSS file and add some boilerplate to it: https://squidfunk.github.io/mkdocs-material/reference/admonitions/#custom-admonitions
2. Add an entry to the icon/admonition theme option.
3. Define a custom sphinx admonition directive for it

It would be nicer if we provided a single option where the user could specify:

• Directive name/names
• CSS class name (maybe same as directive name?)
• Default title
• Colors
• Icon

Ideally, this would emit the necessary additional CSS to a new combined bundle that contains the static pre-generated CSS bundle with any dynamically-generated CSS appended. That way there is still a single bundle, and we avoid duplicating the additional CSS on every HTML page, as occurs with the current icon/admonition theme option.

• adds pyright to npm deps
• pyright config is in pyproject.toml
  • I have meticulously went through all the checks and adjusted those that were turned off by default.
  • Any checks that are disabled should have a conclusion (in CAPS) and a brief rationality
• CI runs pyright in the npm run check step. Therefore, all python dependencies (packaging, linting, and docs) are installed before running npm run check
  • created a new requirements-dev.txt (named so it shows next to the other requirements.txt file) to declare some extra typing stub libs (as well as pylint and black).
• added some simple stubs for dependencies, namely pymdownx.keys_db and sphinxcontrib.details.directive.

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.

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.

Includes

• fix for Windows paths
• fix for unresolved cross-refs in the new docs
• support for \ and @ prefixed Doxygen commands
• support for @retval command
• support for param direction(s)
• add new strip_comment() to accommodate for all forms of C++ comment syntax

I also enabled verbosity in the cpp.apigen demo and added a line that shows the number of declarations that will be parsed.

add a simple pybind11 pkg, titled "issue_134" for testing.

This doesn't include a new pytest to build the docs for this simple pybind11 pkg (yet)

Fixes #92.

This is based on #116.

TODO:

• [ ] Document how to use separate build step to preprocess C++ input header using normal compiler
• [ ] Document how to extract compiler flags (especially include paths) from normal build process
• [ ] Add unit tests of api_parser
• [ ] Add unit tests of apigen
• [ ] Add example of explicit(bool) auto-conversion
• [ ] Support :order: option as in Python apigen
• [ ] Support equivalent of python_apigen_default_groups / python_apigen_default_order
• [ ] Support rST-style :group: and :relates: in addition to doxygen-style commands
• [ ] Support @-prefixed doxygen commands in addition to \-prefixed ones (e.g. @param in addition to \param)
• [ ] Add example of documenting multiple signatures together (by leaving no space between them)
• [ ] Add tests of source location (e.g. in signature, and in docstring)
• [ ] Add tests and documentation of NONITPICK

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'm currently using the RTD Sphinx theme, for which I've added templates to add links to these indices the the TOC as described in this StackOverflow answer. See the Indices and tables section in the sidebar at http://www.mos6581.org/rinohtype/0.5.4/ for the result.

I've been trying to do the same in sphinx-immaterial, but the templates do not seem to define blocks where these can easily be injected. My knowledge of Jinja is limited, but I think it is necessary to replace all of the site_nav block in layout.html, duplicating all of the block's contents and injecting the links. Here is my attempt so far:

{% extends "!layout.html" %}

{% block site_nav %}

  <!-- Main navigation -->
  {% if nav %}
    {% if page and page.meta and page.meta.hide %}
      {% set hidden = "hidden" if "navigation" in page.meta.hide %}
    {% endif %}
    <div
      class="md-sidebar md-sidebar--primary"
      data-md-component="sidebar"
      data-md-type="navigation"
      {{ hidden }}
    >
      <div class="md-sidebar__scrollwrap">
        <div class="md-sidebar__inner">
          {% include "partials/nav.html" %}

          <ul class="md-nav__list">
            <li class="md-nav__item md-nav__item--nested">
              <nav class="md-nav" aria-label="User Manual" data-md-level="1">
                <span class="md-nav__icon md-icon"></span>
                <span class="md-ellipsis">Indices and tables</span>
                <ul class="md-nav__list">
                  <li class="md-nav__item">
                    <a href="{{pathto('genindex.html', 1)}}" class="md-nav__link">
                      <span title="intro (document)" class="md-ellipsis">Index</span>
                    </a>
                  </li>
                  <li class="md-nav__item">
                    <a href="{{pathto('py-modindex.html', 1)}}" class="md-nav__link">
                      <span title="install (document)" class="md-ellipsis">Module Index</span>
                    </a>
                  </li>
                </ul>
              </nav>
          </ul>

        </div>
      </div>
    </div>
  {% endif %}

  <!-- Table of contents -->
  {% if not "toc.integrate" in features %}
    {% if page and page.meta and page.meta.hide %}
      {% set hidden = "hidden" if "toc" in page.meta.hide %}
    {% endif %}
    <div
      class="md-sidebar md-sidebar--secondary"
      data-md-component="sidebar"
      data-md-type="toc"
      {{ hidden }}
    >
      <div class="md-sidebar__scrollwrap">
        <div class="md-sidebar__inner">
          {% include "partials/toc.html" %}
        </div>
      </div>
    </div>
  {% endif %}

{% endblock %}

This produces a this suboptimal result:

I was hoping there is a better way to approach this.

Actually, I think a better fix would be for Sphinx to allow including these indices in a toctree. Or perhaps sphinx-immaterial could provide an option to insert links to the indices at the bottom of the navigation tree?

What happened:

I'm trying to use the content.code.annotate feature, but I can't get it to work inside of a yaml code block. There is also almost no documentation for getting it to work inside sphinx rst.

I've dug into the issue, and it appears that the element that is being passed into the "findCandidateList" function is the <div class="highlight" />. The function accesses the next sibling element which is expected to be an ordered list element, but the div has an extra parent.

https://github.com/jbms/sphinx-immaterial/blob/a944f278cb7f1066482e59b9a17d3311624cd01e/src/assets/javascripts/components/content/code/_/index.ts#L98

If the code were to access the sibling of the parent of the container I believe this code would work correctly, but as of now it just returns null and exits.

Here's an example of my rendered code block:

Environment

Sphinx: v5.1.1 sphinx-immaterial: 0.9.1

Hi,

When I search on this sphinx-immaterial website and choose a Python object it always takes me to the top of the page instead of directly to the Python object that I'm searching for:

https://josiahwolfoberholtzer.com/uqbar/

For example,

If I search for the query add:

When I get redirected it takes me to the top of the page and to this url:

https://josiahwolfoberholtzer.com/uqbar/api/uqbar/containers/dependency_graph.html#

What sphinx-immaterial needs to do is redirect to this url instead:

https://josiahwolfoberholtzer.com/uqbar/api/uqbar/containers/dependency_graph.html#uqbar.containers.dependency_graph.DependencyGraph.add

So that I can arrive here:

This issue also happens on a local project.

Is this a bug or am I missing some feature that needs to be enabled?

For the markdown_it module used by myst_parser the text must be passed as explicit string.

This PR ensures the title_text from self.default_title in custom_admonitions.py is converted from <class 'sphinx.locale._TranslationProxy'> to string.

This PR fixed #196.

I've changed from recommonmark to MyST renderer for markdown and now get an exception error if I try to create the documentation with sphix:

Exception occurred:
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/markdown_it/main.py", line 283, in parseInline
    raise TypeError(f"Input data should be a string, not {type(src)}")
TypeError: Input data should be a string, not <class 'sphinx.locale._TranslationProxy'>
The full traceback has been saved in /tmp/sphinx-err-c8i0_190.log, if you want to report the issue to the developers.

The stacktrace indicates an issue in the mardown_it package which is used by myst_parse

Traceback (most recent call last):
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/cmd/build.py", line 281, in build_main
    app.build(args.force_all, args.filenames)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/application.py", line 347, in build
    self.builder.build_update()
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 310, in build_update
    self.build(to_build,
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 326, in build
    updated_docnames = set(self.read())
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 433, in read
    self._read_serial(docnames)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 454, in _read_serial
    self.read_doc(docname)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/builders/__init__.py", line 510, in read_doc
    publisher.publish()
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/docutils/core.py", line 224, in publish
    self.document = self.reader.read(self.source, self.parser,
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx/io.py", line 104, in read
    self.parse()
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/docutils/readers/__init__.py", line 76, in parse
    self.parser.parse(self.input, document)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/parsers/sphinx_.py", line 69, in parse
    parser.render(inputstring)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/markdown_it/main.py", line 267, in render
    return self.renderer.render(self.parse(src, env), self.options, env)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 231, in render
    self._render_tokens(list(tokens))
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 210, in _render_tokens
    self.rules[f"render_{child.type}"](child)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 603, in render_fence
    return self.render_directive(token)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 1239, in render_directive
    nodes_list = self.run_directive(name, arguments, content, position)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 1323, in run_directive
    result = directive_instance.run()
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mocking.py", line 472, in run
    self.renderer.nested_render_text(
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 339, in nested_render_text
    self._render_tokens(tokens)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 210, in _render_tokens
    self.rules[f"render_{child.type}"](child)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 1134, in render_colon_fence
    return self.render_fence(token)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 603, in render_fence
    return self.render_directive(token)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 1239, in render_directive
    nodes_list = self.run_directive(name, arguments, content, position)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 1323, in run_directive
    result = directive_instance.run()
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/sphinx_immaterial/custom_admonitions.py", line 208, in run
    textnodes, messages = self.state.inline_text(title_text, self.lineno)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mocking.py", line 199, in inline_text
    return self.inliner.parse(text, lineno, self.memo, self._renderer.current_node)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mocking.py", line 77, in parse
    self._renderer.nested_render_text(text, lineno, inline=True)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/myst_parser/mdit_to_docutils/base.py", line 323, in nested_render_text
    tokens = self.md.parseInline(text, self.md_env)
  File "/apps/home/user/test123/.tox/docs/lib/python3.10/site-packages/markdown_it/main.py", line 283, in parseInline
    raise TypeError(f"Input data should be a string, not {type(src)}")
TypeError: Input data should be a string, not <class 'sphinx.locale._TranslationProxy'>

The issue is that the parseInline function in the main.py module of markown-it-py expects to receive a string type object but it seems to get a sphinx.locale._TranslationProxy instead from the sphinx_immaterial extension.

If I use a different theme like standard alabaster, then I don't get this issue and the document renders as expected.

As a workaround I changed the string check in line 283 in mardown-it-py as below, it works.

    def parseInline(self, src: str, env: MutableMapping | None = None) -> list[Token]:
        """The same as [[MarkdownIt.parse]] but skip all block rules.

        :param src: source string
        :param env: environment sandbox

        It returns the
        block tokens list with the single `inline` element, containing parsed inline
        tokens in `children` property. Also updates `env` object.
        """
        env = {} if env is None else env
        if not isinstance(env, MutableMapping):
            raise TypeError(f"Input data should be an MutableMapping, not {type(env)}")
        if not isinstance(src, str):
            raise TypeError(f"Input data should be a string, not {type(src)}")
        if not isinstance(src, str):
            # Workaround: disable exception and convert to string
            # raise TypeError(f"Input data should be a string, not {type(src)}")
            src = str(src)
        state = StateCore(src, self, env)
        state.inlineMode = True
        self.core.process(state)
        return state.tokens

But I think the correct solution should be that this sphinx-immaterial theme correctly passes a string object to the markdown parser and not <class 'sphinx.locale._TranslationProxy'> as it currently seems to do.

Hello guys!

I'm having a bit of trouble replicating the following behaviour, where the search text is highlighted bellow the search box:

I've replicated the project's config.py, and also the text contained in the rst file, but no highlight is shown in the search box:

Is this a known issue? I'm acessing the HTML via google chrome and file:///

Description I would like to use the Recursive Google Fonts but when I configure the html_theme_options, fonts, I get a Sphinx-Immaterial extension error.

What's it all about? I want to use the Recursive font as the text font in my project but I keep getting a 400 Client Error: Bad Request url error when I build my Sphinx project. From my research, I realised that the way Sphinx-Immaterial requests fonts from Google Fonts won't always work because some fonts do not provide other font styles like italics.

For example:

In my project, I want to use the Recursive font which does not provide italic versions of the font. As a result, if Sphinx-Immaterial tries fetching this URL: https://fonts.googleapis.com/css?family=Recursive:700i, it will get a Bad Request error (status-code: 400).

What should happen: Sphinx-Immaterial downloads the Google Fonts specified by the user, caches them (using the cache specified by sphinx_immaterial_external_resource_cache_dir), and includes the fonts in the built documentation.

What happened instead: I get the following Sphinx-Immaterial extension error:

Extension error (sphinx_immaterial.external_resource_cache):
Handler <function _builder_inited at 0x7fd07afc7370> for event 'builder-inited' threw an exception (exception: 400 Client Error: Bad Request for url: https://fonts.googleapis.com/css?family=Recursive:700i)

How to reproduce this bug:

1. Create projectA:

   mkdir projectA
   cd projectA
   sphinx-quickstart 
   

2. Install Sphinx-Immaterial and configure projectA by adding the following lines to projectA/source/conf.py:

   extensions = ["sphinx_immaterial"]
   html_theme = "sphinx_immaterial"
   html_theme_options = {
   	# Other Sphinx-Immaterial configuration
   	"font": {
   		"text": "Recursive"
   	},
   }
   

3. Build documentation using make html or sphinx-build -b html . ./_build/html

Browser(s) and Device(s) observed on:

• Device: Ubuntu Linux
• Browser: Google Chrome
• Python version: 3.9.13
• Sphinx version: 5.3.0
• Sphinx-Immaterial: 0.11.0

I hope the description helps to reproduce the issue :)