-
Notifications
You must be signed in to change notification settings - Fork 54
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Combined directive for only
and code-block
?
#19
Comments
Seems useful and trivial to implement, although I may be missing something important. 4 years, and not even a comment, though. Not sure if anyone really cares. I started doing conversion of the documentation (took notes on the entire documentation, and completed about 3 chapters of actual conversion so far), but ran into much harder issues to solve. As part of that process, though, I added an "only-code" directive to conf.py (maybe the "wrong" place, but all that other stuff is in there, as well): .. only-code:: python
# code
.. only-code:: cpp
// code # addnodes.only is the default only node
from sphinx import addnodes
# but for variations, it's varations.VariationNode
from variations import VariationNode
# I've no idea what the difference is, but I switched to the sphinx version
#from docutils.parsers.rst.directives.body import CodeBlock
from sphinx.directives.code import CodeBlock ... class OnlyCode(CodeBlock):
def run(self):
n = CodeBlock.run(self)
n[0] = VariationNode("", n[0], **self.options) # or addnodes.only
n[0]['expr'] = self.arguments[0] # expr is what only switches on
return n ... # in setup(app)
app.add_directive("only-code", OnlyCode) I tried making the class used as "only" selected the same way the variations code does it, but failed. I don't know Python, Sphinx, or docutils well enough, and I really don't want to. Just don't expect it to work outside of the supported variations target, which I have not managed to do, anyway (PDF output fails to build for me). Of course this only makes things very slightly easier and cleaner. It's beyond the scope of this issue, but what would make things much cleaner and easier would be to eliminate the need to duplicate an entire paragraph (thus creating a maintenance issue) just to change a few words. In rst, this would mean the use of a "role", rather than a "directive" (directives introduce a new paragraph, and substitutions can't work because they are assigned before "only" does its filtering). I added some simple ones for my C documentation efforts (in fact, the above code is based on that, rather than the other way around), but the roles only support plain text because roles can't nest (which soured me on the whole idea of rst, really; I prefer (La)TeX anyway, but even HTML supports nested spans). I did manage to support basic markup such as * for italics/bold, but what I really wanted was to change the symbol names (including the use of :: and -> instead of . where needed, and the elimination of (just) the subsystem prefix in C ), preferably automatically based on ? (I guess the default realm?). I'd have to really modify all the existing roles that are affected, as well, and I don't really know/want to know Python, Sphinx, docutils, or how the Panda3D-specific sphinx code works, well enough (read: at all) for that. |
This pattern is extremely common:
We should consider whether we want to introduce a shorthand for this kind of thing.
The text was updated successfully, but these errors were encountered: