From: Michael L. <li...@pr...> - 2013-12-29 00:38:02
|
I'm currently trying to make a directive that allows some special things to be done in the page. Mostly, it allows me to simplify the format used to stick data on a page. I used app.add_directive() to add the directive. I also used app.add_node() to get to the point where I have data in a function. I think I'm doing alright. This function now sticks things on the page, but... I can't figure out how to register a heading. The heading I want to register will always be the same level. I also need to figure out how to print that to the screen. A very basic example of what I'm trying to do is... .. mydirective:: fuzzy A|b|c|d wuzzy was a bear I would like to do two things with this directive. I first want the argument to generate a title and the first line to generate a table, followed by the remaining stuff. If I weren't making this directive, it would be something more like this... fuzzy ~~~~~ ========= = *Title 1* A *Title 2* b *Title 3* c *Title 4* d ========= = wuzzy was a bear This is a grossly simplified version, but basically explains exactly what I need. I need to first, register that heading, then I need to generate a table. I really hope this makes sense. I'm struggling to explain it and really hope that someone can help me figure this out. Thanks! -- Michael Lustfield |
From: Guenter M. <mi...@us...> - 2013-12-29 17:32:14
|
On 2013-12-29, Michael Lustfield wrote: > I'm currently trying to make a directive that allows some special > things to be done in the page. Mostly, it allows me to simplify the > format used to stick data on a page. > I used app.add_directive() to add the directive. I also used > app.add_node() to get to the point where I have data in a function. I > think I'm doing alright. I don't know about ``app``, but as this seems to work for you, this is no problem. (Otherwise you should tell a bit more about the framework you use.) > This function now sticks things on the page, but... I can't figure out > how to register a heading. The heading I want to register will always > be the same level. >From the explanations further down, I suppose you want to add a heading element to the document tree. In the docutils sources, there are examples of both: directives that add more than one node to the document tree and a directive that adds a heading node. The right combination of these should do what you expect. > I also need to figure out how to print that to the screen. Do you mean the HTML/PDF/ODF or whatever output? Once you have the correct element node added to the document tree (at the right place), conversion to the output format should be done by the writer without further effort. This is the nice thing about the separation of parsing, transforming and writing steps. > A very basic example of what I'm trying to do is... > .. mydirective:: fuzzy > A|b|c|d > wuzzy > was a > bear > I would like to do two things with this directive. I first want the > argument to generate a title and the first line to generate a table, > followed by the remaining stuff. > If I weren't making this directive, it would be something more like this... > fuzzy > ~~~~~ >========= = > *Title 1* A > *Title 2* b > *Title 3* c > *Title 4* d >========= = > wuzzy > was a > bear > This is a grossly simplified version, but basically explains exactly what I > need. I need to first, register that heading, then I need to generate a > table. > I really hope this makes sense. I'm struggling to explain it and really hope > that someone can help me figure this out. For me, a help in creating such directives was to re-create the intended behaviour in rst (as you do above) and then have a look at the rst2pseudoxml or rst2xml output to see what the relevant part of the document tree looks like. Then I go to docutils/docutils/parsers/rst/directives and look for examples to copy and paste and adapt. Günter |
From: Michael L. <li...@pr...> - 2013-12-30 02:29:37
|
Yup, it's adding a heading node that I'm trying to do and I'm also trying to recreate what rst does. It looks, however, like I should be trying to do this through sphinx-doc and not through docutils since I'm actually writing a sphinx-doc plugin. I struggle with where one stops and where the other begins. :( Thanks for helping me figure out what it actually is that I'm trying to do! |
From: Michael L. <li...@pr...> - 2013-12-30 05:50:03
|
I think I'm finally starting to get this. sphinx-doc uses docutils to do most of its work. Docutils provides the parsing of rst along with pretty much all of the work that sphinx-doc does. So... it is indeed docutils that I need to work with to make this work. On Sun, Dec 29, 2013 at 11:31 AM, Guenter Milde <mi...@us...> wrote: > On 2013-12-29, Michael Lustfield wrote: > > > This function now sticks things on the page, but... I can't figure out > > how to register a heading. The heading I want to register will always > > be the same level. > > From the explanations further down, I suppose you want to add a heading > element to the document tree. In the docutils sources, there are examples > of both: directives that add more than one node to the document tree and > a directive that adds a heading node. The right combination of these > should do what you expect. > > That sounds exactly like what I need (add heading node). I'm not finding any examples of doing that, though. > > I also need to figure out how to print that to the screen. > > Do you mean the HTML/PDF/ODF or whatever output? Once you have the > correct element node added to the document tree (at the right place), > conversion to the output format should be done by the writer without > further effort. This is the nice thing about the separation of parsing, > transforming and writing steps. > > I guess I have this part figured out now. I'll probably be wrong, but I think I have it. > > > A very basic example of what I'm trying to do is... > > > .. mydirective:: fuzzy > > > A|b|c|d > > wuzzy > > was a > > bear > > > I would like to do two things with this directive. I first want the > > argument to generate a title and the first line to generate a table, > > followed by the remaining stuff. > > > If I weren't making this directive, it would be something more like > this... > > > fuzzy > > ~~~~~ > > >========= = > > *Title 1* A > > *Title 2* b > > *Title 3* c > > *Title 4* d > >========= = > > > wuzzy > > was a > > bear > > > > This is a grossly simplified version, but basically explains exactly > what I > > need. I need to first, register that heading, then I need to generate a > > table. > > > I really hope this makes sense. I'm struggling to explain it and really > hope > > that someone can help me figure this out. > > For me, a help in creating such directives was to re-create the intended > behaviour in rst (as you do above) and then have a look at the > rst2pseudoxml > or rst2xml output to see what the relevant part of the document tree looks > like. Then I go to docutils/docutils/parsers/rst/directives and look for > examples to copy and paste and adapt. > That sounds like a scary trip. I'll try to run through there and figure it out. |
From: Michael L. <li...@pr...> - 2013-12-30 06:53:03
|
The XML part of it was a far less scary trip than I expected. I can see the exact XML that I want to produce. Is this XML just a step between parsing and generating? If so, is it possible to just inject it? I'm not sure where I would do that with sphinx-doc. I'm guessing there's a prettier way to put this in there, but if I'm able to simply throw XML into the generation, then this will give me the exact result I'm looking for. |
From: Marc 'B. R. <ma...@ri...> - 2013-12-30 11:08:19
|
On 30/12/13 07:52, Michael Lustfield wrote: > The XML part of it was a far less scary trip than I expected. I can see > the exact XML that I want to produce. Is this XML just a step between > parsing and generating? If so, is it possible to just inject it? The XML is a representation or serialisation of the internal document model that is the step between parsing and generating output formats. So it has nothing to do with the process of generating HTML for instance. You are generating it *instead* of HTML to see the internal structure. It's a debugging and developing aid. Ciao, Marc 'BlackJack' Rintsch -- A train station is where trains stop. A bus station is where busses stop. A Work Station is where ... |
From: Michael L. <li...@pr...> - 2013-12-31 00:55:32
|
On Mon, Dec 30, 2013 at 5:08 AM, Marc 'BlackJack' Rintsch <ma...@ri...>wrote: > On 30/12/13 07:52, Michael Lustfield wrote: > > The XML part of it was a far less scary trip than I expected. I can see > > the exact XML that I want to produce. Is this XML just a step between > > parsing and generating? If so, is it possible to just inject it? > > The XML is a representation or serialisation of the internal document > model that is the step between parsing and generating output formats. > So it has nothing to do with the process of generating HTML for > instance. You are generating it *instead* of HTML to see the internal > structure. It's a debugging and developing aid. > > That makes sense. I can see what XML I want to produce. That does indeed help me understand the structure. Where can find examples that will help me get these elements stuck into the doc tree? |
From: David G. <go...@py...> - 2014-01-03 15:03:45
|
On 30 December 2013 18:55, Michael Lustfield <li...@pr...> wrote: > Where can find examples that will help me get these elements stuck into the > doc tree? Look in docutils/parsers/rst/directives/. All the directives are defined there. Look at http://docutils.sourceforge.net/docs/ref/rst/directives.html for a directive that does something like what you want, and then look for it's code in the directory above. Realize that it won't be exactly what you want, just a hint. -- David Goodger <http://python.net/~goodger> |