From: The C. <cad...@gm...> - 2007-11-15 10:28:14
|
I'd like to use docutils in my programs to convert simple reST-formatted strings to html. Just like how Markdown does it. Markdown is extremely handy, but since I've been using reST a lot lately, I figured I may as well try it for generating html snippets as well. The code I've got (I think I previously found it from searching the ML, rather than in the actual docs) is this: import docutils.core def rst2html(some_text): """ Convert from reST to html snippets. """ overrides = {'doctitle_xform': None, 'file_insertion_enabled': 0, 'raw_enabled': 0, 'initial_header_level': 2, 'cloak_email_addresses': 1, 'toc_backlinks': 'none'} parts = docutils.core.publish_parts(source=some_text, writer_name='html', settings_overrides=overrides) fragment = parts['fragment'] return fragment But my headings (ex. <h2>'s) are still looking like links. How can I get the html without the ``<a id="..." name="..."></a>`` tags around the heading text? I just want simple bits of reST-formatted text converted to simple bits of html. I was reading the docs at http://docutils.sourceforge.net/docs/user/config.html , and they *seem* to correspond to what I'm passing to docutils.core.publish as settings_overrides, but that page of documentation only refers to those various settings as being used for config files... If I'm using them correctly here, it would be helpful if (somewhere) it said, "by the way, you can also specify these as keys in a dict that you pass as ``settings_overrides`` to docutils.core.publish. I've been guessing at what to put after ``'toc_backlinks':``, but neither 0, 'none', nor 'false' seem to work. By the way, I'm glad that there seems to be pretty voluminous docs for docutils, but I think they could be even better if they contained more examples as well as pieces at the beginning of each doc saying something like, "This document explains how to do thus and so. You'd want to do that if you were trying to make docutils do such-and-such.". Incidentally, it would be really handy if the ``rst2html`` tool had an option to do exactly what I'm asking for above. Seems like a lot of people would use it that way. Is there any particular reason there isn't such an option? Or am I missing it? Just curious. Thanks. |
From: The C. <cad...@gm...> - 2007-11-15 10:37:13
|
On Nov 15, 2007 5:28 AM, The Cadet <cad...@gm...> wrote: > I was reading the docs at > http://docutils.sourceforge.net/docs/user/config.html , and they > *seem* to correspond to what I'm passing to docutils.core.publish as Typo: s/publish/publish_parts()/ > settings_overrides, but that page of documentation only refers to > those various settings as being used for config files... If I'm using > them correctly here, it would be helpful if (somewhere) it said, "by > the way, you can also specify these as keys in a dict that you pass as > ``settings_overrides`` to docutils.core.publish. I've been guessing at Typo #2 -- that last line should be: > ``settings_overrides`` to docutils.core.publish_parts()". I've been guessing at (note closing double-quote in there). Thanks. |
From: Ben F. <big...@be...> - 2007-11-15 12:25:51
|
"The Cadet" <cad...@gm...> writes: > But my headings (ex. <h2>'s) are still looking like links. How can I > get the html without the ``<a id="..." name="..."></a>`` tags around > the heading text? I just want simple bits of reST-formatted text > converted to simple bits of html. > [...] > Incidentally, it would be really handy if the ``rst2html`` tool had an > option to do exactly what I'm asking for above. $ rst2html --help | grep backlinks --toc-entry-backlinks Enable backlinks from section headers to table of --toc-top-backlinks Enable backlinks from section headers to the top of --no-toc-backlinks Disable backlinks to the table of contents. --footnote-backlinks Enable backlinks from footnotes and citations to their --no-footnote-backlinks Disable backlinks from footnotes and citations. $ rst2html --version rst2html (Docutils 0.4.1 [repository]) -- \ "I was born by Caesarian section. But not so you'd notice. It's | `\ just that when I leave a house, I go out through the window." | _o__) -- Steven Wright | Ben Finney <be...@be...> |
From: David G. <go...@py...> - 2007-11-15 16:09:07
|
Your code works just fine for me. Which version of Docutils, Python are you running, and what OS? Try running your text through the command-line version: rst2html.py --dump-settings --link-stylesheet input.txt output.html Add --no-toc-backlinks and try again. Compare the settings that are sent to stderr. It looks like the Docutils Configuration doc does have a typo though: it shouldn't specify 'none' but None or False (no quotes, note case). However, the way Docutils is coded, anything other than 'entry' or 'top' should have the same effect as None or False. It shouldn't make a difference, but you could try changing 'toc_backlinks': 'none'} to 'toc_backlinks': None} I will fix the entry in Docutils Configuration. On 11/15/07, The Cadet <cad...@gm...> wrote: > it would be helpful if (somewhere) it said, "by > the way, you can also specify these as keys in a dict that you pass as > ``settings_overrides`` to docutils.core.publish. That's covered here: http://docutils.sourceforge.net/docs/api/runtime-settings.html The Docutils Configuration doc is aimed at non-developer users, but I will add a link to the doc above. > I've been guessing at what to put after ``'toc_backlinks':``, but > neither 0, 'none', nor 'false' seem to work. 0 ought to work too. Note that 'false' is NOT a boolean false value in Python. You want False (no quotes, capital F). > By the way, I'm glad that there seems to be pretty voluminous docs for > docutils, but I think they could be even better if they contained more > examples as well as pieces at the beginning of each doc saying > something like, "This document explains how to do thus and so. You'd > want to do that if you were trying to make docutils do > such-and-such.". Good idea. Patches are welcome! > Incidentally, it would be really handy if the ``rst2html`` tool had an > option to do exactly what I'm asking for above. Seems like a lot of > people would use it that way. Is there any particular reason there > isn't such an option? Or am I missing it? Just curious. rst2html is a tool for creating complete HTML documents. There is no one portion which all users would want. You want the 'fragment' part, others might want 'body' and 'title' separately, etc. That's what the API is for. And in most cases, portions are only needed from within code, not from the command line. Alternate answer: this is an open source project, and patches are welcome! -- David Goodger <http://python.net/~goodger> |
From: The C. <cad...@gm...> - 2007-11-15 22:30:45
|
On Nov 15, 2007 11:09 AM, David Goodger <go...@py...> wrote: > Your code works just fine for me. > Which version of Docutils, Python are you running, and what OS? Thanks for the reply, David. I'm using Ubuntu 7.10 (Gutsy). But I upgraded from the previous version, upon which I think I installed docutils manually (not using apt). During the upgrade to 7.10, if memory serves, I think there was an issue, and I had to manuall rm the docutils modules to get things to work. I may have botched things up. $ dpkg -l | grep docut ii python-docutils 0.4-4 [snip] $ rst2html -V rst2html (Docutils 0.4.1 [repository]) $ python -V Python 2.5.1 > Try running your text through the command-line version: > > rst2html.py --dump-settings --link-stylesheet input.txt output.html > > Add --no-toc-backlinks and try again. Compare the settings that are > sent to stderr. $ diff before after 56c56 < 'toc_backlinks': 'entry', --- > 'toc_backlinks': False, > It looks like the Docutils Configuration doc does have a typo though: > it shouldn't specify 'none' but None or False (no quotes, note case). > However, the way Docutils is coded, anything other than 'entry' or > 'top' should have the same effect as None or False. It shouldn't make > a difference, but you could try changing > > 'toc_backlinks': 'none'} > > to > > 'toc_backlinks': None} > > I will fix the entry in Docutils Configuration. > > On 11/15/07, The Cadet <cad...@gm...> wrote: > > it would be helpful if (somewhere) it said, "by > > the way, you can also specify these as keys in a dict that you pass as > > ``settings_overrides`` to docutils.core.publish. > > That's covered here: > http://docutils.sourceforge.net/docs/api/runtime-settings.html > > The Docutils Configuration doc is aimed at non-developer users, but I > will add a link to the doc above. You might add at the top of the docutils configuration doc something like, "This document is aimed at non-developers. However, the information here is analogous to and can be directly applied to use of the docutils API used by programmers. That is, any settings you can set in your docutils configuration file (described below), can also be set programmatically when passing arguments to ``docutils.core.publish_parts()``". > > I've been guessing at what to put after ``'toc_backlinks':``, but > > neither 0, 'none', nor 'false' seem to work. > > 0 ought to work too. Note that 'false' is NOT a boolean false value > in Python. You want False (no quotes, capital F). > > > By the way, I'm glad that there seems to be pretty voluminous docs for > > docutils, but I think they could be even better if they contained more > > examples as well as pieces at the beginning of each doc saying > > something like, "This document explains how to do thus and so. You'd > > want to do that if you were trying to make docutils do > > such-and-such.". > > Good idea. Patches are welcome! Unfortunately, as a fairly new user, it's very difficult to write doc patches about software I don't yet understand. Chicken and egg. However, I think input from new users is still valuable, because it may give you an idea of what a new user perceives as missing or unclear (documentation-wise). It's no fault of experienced developers that they often forget what it's like to see a project's docs for the first time. > > Incidentally, it would be really handy if the ``rst2html`` tool had an > > option to do exactly what I'm asking for above. Seems like a lot of > > people would use it that way. Is there any particular reason there > > isn't such an option? Or am I missing it? Just curious. > > rst2html is a tool for creating complete HTML documents. There is no > one portion which all users would want. You want the 'fragment' part, > others might want 'body' and 'title' separately, etc. That's what the > API is for. And in most cases, portions are only needed from within > code, not from the command line. > > Alternate answer: this is an open source project, and patches are welcome! Are you interested in including an uber-simple ``rst2plainhtmlsnippet.py`` script with the docutils distribution? Maybe something that could be a slightly-extended version of the code I posted in my original message? Note: the fact is that as reST gains popularity, various users (using various languages) may want to be able to quickly and easily snap in a way to convert reST snippets to clean html snippets. If rst2html had an equivalent behaviour available, similar to the default behaviour of Markdown.pl, then it would be a toss up for new users. They could pick either and get a working (but lazy) solution in one line of code (something like ``os.system('rst2plainhtmlsnippet input.txt output.html')``). And that approach would work from Perl, PHP, Ruby, whatever. Sometimes I've heard this sort of thing discussed in terms of "allowing users to just get their work done even if it might be unsightly at times (a la Perl)", vs. "guiding users to only do things by the book to keep things uniform (a la Python)". I'm not saying I always agree with that comparison, but I think it's probably a big reason why you find Perl scripts in every little weird crevice of the Internet duct-taping things together. Thanks. |