> > I'm trying to learn how to extend Sphinx. I need to create new directives
> > and other stuff, so I tried to start off with a simple directive, which
> > encloses the contents in div tags of certain class in the html output.
>
> Did you find: Creating reStructuredText Directives
> (http://docutils.sourceforge.net/docs/howto/rst-directives.html)
> from the Docutils documentation?
>
> It may need adaption regarding the way the code is "injected" but should
> also work for Sphinx (which can be regarded as a "wrapper" around
> Docutils).
>
Thanks for the hint, I had looked at it, but not dedicated enough time. The
trick was to use "self.state.nested_parse()". Here is a code that seems to
work, in case anybody else needs:
from docutils import nodes
from docutils.parsers.rst import Directive
class example_node(nodes.Element):
pass
class Examp(Directive):
has_content = True
def run(self):
text = '\n'.join(self.content)
node = example_node(rawsource=text)
self.state.nested_parse(self.content, self.content_offset,
node)
return [node]
def setup(app):
app.add_directive('example', Examp)
app.add_node(example_node, html=(visit_example, depart_example))
def visit_example(self, node):
self.body.append(self.starttag(node, 'div', CLASS='example'))
def depart_example(self, node):
self.body.append('</div>\n')
The choice of nodes.Element is a bit arbitrary, I did some trial and error
and seemed to work :-P
At least now I can go on writing my documents with the new directive.
>
> > BTW, I've been dealing with this for quite some time. All the ideas I got
> > are from code I read from other people. I tried to follow the tutorial,
> but
> > it has been of no help. In general, I feel like Sphinx and Docutils are
> > poorly documented for newbies, but maybe it's just me.
>
> You are not alone.
That's a relief :-)
Now, a honest question. How should I know that "nested_parse" even exists?
I had to plunge into the code to find that "nested_parse" is a function
inside class docutils.parsers.rst.states.RSTState (the only info I get from
Directive.__doc__ is that state is "the state which called the directive
function"), but how am I supposed to know what the states are?
I'm asking sincerely here, I don't know if I'm missing something in my
workflow. How do you know which methods, attributes or variables are
available? Do you use an specialised editor which tells all this? (I'm
using Emacs for the record.) Is there any documentation covering this? Do
you just wander through the code and try to learn all what is available?
Regards,
Keta
On Mon, Oct 14, 2013 at 4:51 PM, Guenter Milde <[email protected]> wrote:
> On 2013-10-12, ketakopter wrote:
>
> > [-- Type: text/plain, Encoding: --]
>
> > Hello,
>
> > I'm trying to learn how to extend Sphinx. I need to create new directives
> > and other stuff, so I tried to start off with a simple directive, which
> > encloses the contents in div tags of certain class in the html output.
>
> Did you find: Creating reStructuredText Directives
> (http://docutils.sourceforge.net/docs/howto/rst-directives.html)
> from the Docutils documentation?
>
> It may need adaption regarding the way the code is "injected" but should
> also work for Sphinx (which can be regarded as a "wrapper" around
> Docutils).
>
> > This is the closest I got:
>
> ...
>
> > However, it is far from satisfactory: the contents are not parsed
> further,
> > e.g. roles inside are not processed.
>
> > Can you point me to the right direction to do this? If possible, I would
> be
> > grateful not only for a code example, but also on hints on where to look
> > and learn more.
>
> Code examples are in the Docutils source code:
>
> docutils/parsers/rst/directives/*.py
>
> > BTW, I've been dealing with this for quite some time. All the ideas I got
> > are from code I read from other people. I tried to follow the tutorial,
> but
> > it has been of no help. In general, I feel like Sphinx and Docutils are
> > poorly documented for newbies, but maybe it's just me.
>
> You are not alone. However, the manpower behind the Docutils and Sphinx
> project is quite limited, so we depend on contributions to improve this
> situation.
>
> Günter
>
>
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to [email protected].
> To post to this group, send email to [email protected].
> Visit this group at http://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/groups/opt_out.
>
--
You received this message because you are subscribed to the Google Groups
"sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To post to this group, send email to [email protected].
Visit this group at http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.
