Closed MiddleMan5 closed 1 year ago
I was also curious if this worked. I saw @jbms add it to the list of supported features but never inquired.
Reminder: The literal blocks produced by sphinx have a extra div wrapped around them when compared to literal blocks produced by mkdocs.
<div class="annotate highlight-yaml notranslate">
<div class="highlight">
<pre id="__code_2">
<span></span>
<button class="md-clipboard md-icon" title="Copy to clipboard" data-clipboard-target="#__code_2 > code"></button>
<code></code>
</pre>
</div>
</div>
<ol class="arabic simple"><li></li></ol>
<div class="highlight">
<pre id="__code_10">
<span></span>
<button class="md-clipboard md-icon" title="Copy to clipboard" data-clipboard-target="#__code_10 > code"></button>
<code></code>
</pre>
</div>
<ol hidden=""><li></li></ol>
This might be why findCandidateList()
fails to locate the list of annotations in sphinx output.
I'm not sure why I added it to the list of supported features --- I definitely didn't test that it worked. Perhaps I just added it by mistake.
I'm not against a simple solution amended to the JS, but only if it truly is a simple solution.
I'm definitely interested in using the feature, we have large yaml file examples in our docs that this is perfect for
Another possibility could be to change code blocks to generate HTML more similar to that generated by mkdocs. Not sure if the extra div is needed for something.
I think sphinx was using the extra div for captions, but we monkeypatched that already. We do already have another issue to monkeypatch literal blocks about placement of line numbers (#158), so maybe we could do that while exploring a solution for this. I thought about monkeypatching the literal blocks right after posting the "amend JS" comment 🤦♂️.
If removing the extra div proves problematic, then we might be able to move the list of annotations into the extra div using a directive. But this would deviate too much from what a migrating user might expect.
After giving it more thought, I'm leaning toward a new directive because
table
style line numbers.I envision the new directive like so:
.. code-block:: yaml
name: Bulid CI # (1)
.. annotations::
1. The name of the CI workflow
A paragraph with (1) annotations.
.. annotations::
1. Look ma, more noise!
We wouldn't have to support any :class:
or :name:
options for the directive since its sole purpose is to inject the list into the parent for the previous node.
Yes, a code-annotations
directive seems like the best solution.
I chose the term annotations
because we might be able to use the same directive when the more general use of annotations makes its way to public releases (2 tiers/funding goals from now). If your looking for uniqueness, we could go with md-annotations
like we use for other directives that port mkdocs-material features to sphinx-immaterial (like content tabs, mermaid graphs, and title-less admonitions).
I think the content.code.annotate
feature won't need to be specified because the directive could append the CSS class annotate
where applicable (apparently tables aren't supported for sizing reasons). Although, adding it to the features list shouldn't break anything when the we're finished implementing it.
Well, I've got a hacky solution almost ready to push, but I found out that adding the annotate
class to the literal_block node doesn't actually affect the highlighted div (generated by the pygments bridge). Currently (in my dev env), it doesn't work when captions are used in the code-block (possibly because the extra div node just for the caption)... It works ok with the feature enabled globally, but the hide comment mechanism in the JS side isn't getting triggered. I'm still exploring this, but my hacky solution is a bit prudent in that it doesn't copy any of the original code from sphinx.writers.html5.HTML5Translator.visit_literal_block()
.
Here's a tease:
Ok, fixed the captions problem. It also doesn't seem to work with line numbers (yet), even though the HTML structure is the exact same as mkdocs. I just pushed what I have to the code-annotations branch.
@MiddleMan5 I'm sorry, I just realized we closed this out but never published it in a release. Currently, real life matters are taking precedence, so you'll have to use the main branch until next release. I'll update this thread when we push out the next release.
If you have trouble installing from main branch (requires npm), then there's the nightly distribution from testPyPI index: https://test.pypi.org/project/sphinx-immaterial/0.10.0.post1.dev8/
@2bndy5 hey thanks for the update, no worries, I noticed that and switched to installing through git and that's been working
Feature is available in v0.11.0
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