From: Neal B. <ndb...@gm...> - 2008-02-29 12:38:41
|
I know this should be obvious, rst was designed for documenting python, right? I've only found doctest block. What is used to put some python source code into my rst? |
From: Martin G. <mg...@da...> - 2008-02-29 12:46:31
|
Neal Becker <ndb...@gm...> writes: Hi again :-) > I know this should be obvious, rst was designed for documenting > python, right? > > I've only found doctest block. What is used to put some python > source code into my rst? I am using Pygments: http://pygments.org/docs/rstdirective/ It works very nicely and can highlight many different languages. -- Martin Geisler VIFF (Virtual Ideal Functionality Framework) brings easy and efficient SMPC (Secure Multi-Party Computation) to Python. See: http://viff.dk/. |
From: Alan G I. <ai...@am...> - 2008-02-29 12:53:14
|
Are the ``code`` and ``source-code`` directives documented somewhere? (Not here: http://docutils.sourceforge.net/docs/ref/rst/directives.html) Thank you, Alan Isaac |
From: Neal B. <ndb...@gm...> - 2008-02-29 13:01:37
|
Martin Geisler wrote: > Neal Becker <ndb...@gm...> writes: > > Hi again :-) > >> I know this should be obvious, rst was designed for documenting >> python, right? >> >> I've only found doctest block. What is used to put some python >> source code into my rst? > > I am using Pygments: > > http://pygments.org/docs/rstdirective/ > > It works very nicely and can highlight many different languages. > That sounds great! There is a note that says: The ReST lexer now recognizes .. sourcecode:: and .. code:: directives and highlights the contents in the specified language if the handlecodeblocks option is true. I'm using a very recent docutils svn, so I should be able to use this? Sorry, I'm a newb. How do I set the 'handlecodeblocks' option? I guess I'd use it like:: .. code:: in_cnt = 0 out_cnt = 0 I get this: rst2latex format.rst --stylesheet=cmlgc > format.tex format.rst:42: (ERROR/3) Unknown directive type "code". |
From: G. M. <mi...@us...> - 2008-02-29 13:53:26
|
On 29.02.08, Neal Becker wrote: > Martin Geisler wrote: > > Neal Becker <ndb...@gm...> writes: > >> I've only found doctest block. What is used to put some python > >> source code into my rst? The standard method is:: if color_not_needed: print "put your code in a literate block" > > I am using Pygments: > > > > http://pygments.org/docs/rstdirective/ > > > > It works very nicely and can highlight many different languages. > > > That sounds great! There is a note that says: > The ReST lexer now recognizes .. sourcecode:: and .. code:: directives and > highlights the contents in the specified language if the handlecodeblocks > option is true. I suppose you need some more context to this note: which ReST lexer does it refer to? -- surely not the standard one! > I'm using a very recent docutils svn, so I should be able to use this? No. Code syntax highlight is not implemented in the standard docutils. There are extensions that can do this, though. For a survey and a proposal for inclusion in docutils, you can see http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html which is part of a sandbox project: http://docutils.sourceforge.net/sandbox/code-block-directive/README.html Günter > Sorry, I'm a newb. How do I set the 'handlecodeblocks' option? > I guess I'd use it like:: > .. code:: > in_cnt = 0 > out_cnt = 0 > I get this: > rst2latex format.rst --stylesheet=cmlgc > format.tex > format.rst:42: (ERROR/3) Unknown directive type "code". > ------------------------------------------------------------------------- > This SF.net email is sponsored by: Microsoft > Defy all challenges. Microsoft(R) Visual Studio 2008. > http://clk.atdmt.com/MRT/go/vse0120000070mrt/direct/01/ > _______________________________________________ > Docutils-users mailing list > Doc...@li... > https://lists.sourceforge.net/lists/listinfo/docutils-users > Please use "Reply All" to reply to the list. |
From: Neal B. <ndb...@gm...> - 2008-02-29 13:09:42
|
The word 'handlecodeblock' does not occur anywhere in the docutils svn. I guess I need to use the other option: external/rst-directive.py. How do I use this? (I have the current pygments svn). |
From: Martin G. <mg...@da...> - 2008-02-29 13:52:08
|
Alan G Isaac <ai...@am...> writes: > Are the ``code`` and ``source-code`` directives > documented somewhere? (Not here: > http://docutils.sourceforge.net/docs/ref/rst/directives.html) I just use the sourcecode directive like this .. sourcecode:: pycon >>> import viff >>> print viff.__version__ 0.3 You can see examples here: http://viff.dk/doc/unit-testing.html with the source here: http://viff.dk/doc/unit-testing.txt The site is built using a slightly modified buildhtml.py file: http://hg.viff.dk/viff.dk/file/tip/buildhtml.py In line 37 I import the pygments_rst file: http://hg.viff.dk/viff.dk/file/tip/pygments_rst.py I hope this helps! -- Martin Geisler VIFF (Virtual Ideal Functionality Framework) brings easy and efficient SMPC (Secure Multi-Party Computation) to Python. See: http://viff.dk/. |
From: Martin G. <mg...@da...> - 2008-02-29 14:05:10
|
"G. Milde" <mi...@us...> writes: > No. Code syntax highlight is not implemented in the standard > docutils. There are extensions that can do this, though. For a > survey and a proposal for inclusion in docutils, you can see > http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html I just read quickly through this and I think the best way to integrate a sourcecode directive is to simply: * Pass it to Pygments for HTML output. Pygments seems to handle most languages and does so with a good parser architecture. * Pass it to listings for LaTeX output. The listings package is (IMHO) the most comprehensive LaTeX package for typesetting code. Using it will ensure that the code looks "normal", e.g., similar to the code in my other LaTeX documents :-) I have only tried the Pygments side and I think it works perfectly. Is there any difficulty in just outputting the code verbatim to a \begin{lstlisting} ... \end{lstlisting} block? -- Martin Geisler VIFF (Virtual Ideal Functionality Framework) brings easy and efficient SMPC (Secure Multi-Party Computation) to Python. See: http://viff.dk/. |
From: Alan G I. <ai...@am...> - 2008-02-29 14:26:53
|
On Fri, 29 Feb 2008, Martin Geisler apparently wrote: > * Pass it to listings for LaTeX output. The listings > package is (IMHO) the most comprehensive LaTeX package for > typesetting code. Using it will ensure that the code > looks "normal", e.g., similar to the code in my other > LaTeX documents :-) These days, it is hard to imagine why anyone would have code in anything besides a lstlisting environment, for sure. In the future that might change. Perhaps it would make sense to replace the ``--use-verbatim-when-possible`` option with a ``--literal-block-env=`` option, so one could just:: --literal-block-env=verbatim or:: --literal-block-env=lstlisting or even better, if possible:: --literal-block-env=lstlisting[language=Python] The idea is that the last would handle the option to produce:: \begin{lstlisting}[language=Python] the_code = in_here \end{lstlisting} This would be very flexible and forward looking. Cheers, Alan Isaac |
From: G. M. <mi...@us...> - 2008-02-29 15:23:42
|
On 29.02.08, Martin Geisler wrote: > "G. Milde" <mi...@us...> writes: > > No. Code syntax highlight is not implemented in the standard > > docutils. There are extensions that can do this, though. For a > > survey and a proposal for inclusion in docutils, you can see > > http://docutils.sourceforge.net/sandbox/code-block-directive/docs/syntax-highlight.html > I just read quickly through this and I think the best way to integrate > a sourcecode directive is to simply: > * Pass it to Pygments for HTML output. Pygments seems to handle most > languages and does so with a good parser architecture. >From a practical point of view, yes. However, the clean solution (which hopefully will be in standard docutils some day) is to use pygments (if available) to parse the content of a code block and create a "rich" doctree node which is then is processed by the writers... This even works already for HTML, but the latex writer creates errors. > * Pass it to listings for LaTeX output. > I have only tried the Pygments side and I think it works perfectly. Is > there any difficulty in just outputting the code verbatim to a > \begin{lstlisting} ... \end{lstlisting} block? Yes. It will not work with standard docutils. See http://docutils.sourceforge.net/sandbox/latex-variants/docs/syntax-highlight-with-listings.html There is, however an experimental latex writer with listings support available: http://docutils.sourceforge.net/sandbox/latex-variants/latex2e_listings/ I just commited updated documentation to the SVN repository, so it will show after the next automatic build. Günter |
From: Martin G. <mg...@da...> - 2008-03-01 11:08:18
|
"G. Milde" <mi...@us...> writes: >> * Pass it to Pygments for HTML output. Pygments seems to handle most >> languages and does so with a good parser architecture. > > From a practical point of view, yes. However, the clean solution > (which hopefully will be in standard docutils some day) is to use > pygments (if available) to parse the content of a code block and > create a "rich" doctree node which is then is processed by the > writers... I can see how it might be easier to get uniform output in different formats if Docutils parses the code itself using Pygments, but on the other hand, then I would actually expect the LaTeX output to look different from the HTML output (e.g., only highlight with bold/italic instead of the full multi-color "fruit-salad" treatment by Pygments.) So I am very happy if the code is passed verbatim to the writer, which can then decide to include it as a literal block (I assume every writer knows about those) or highlight it in an appropriate way. > [...] > > There is, however an experimental latex writer with listings support > available: > http://docutils.sourceforge.net/sandbox/latex-variants/latex2e_listings/ Good to know, thanks for the link! -- Martin Geisler VIFF (Virtual Ideal Functionality Framework) brings easy and efficient SMPC (Secure Multi-Party Computation) to Python. See: http://viff.dk/. |
From: Alan G I. <ai...@am...> - 2008-02-29 12:49:07
|
On Fri, 29 Feb 2008, Neal Becker apparently wrote: > What is used to put some python source code > into my rst? http://docutils.sourceforge.net/docs/user/rst/quickref.html#literal-blocks You can also use the ``include`` directive. hth, Alan Isaac |
From: Martin G. <mg...@da...> - 2008-02-29 15:27:27
|
Alan G Isaac <ai...@am...> writes: > On Fri, 29 Feb 2008, Martin Geisler apparently wrote: >> * Pass it to listings for LaTeX output. The listings package is >> (IMHO) the most comprehensive LaTeX package for typesetting code. >> Using it will ensure that the code looks "normal", e.g., similar to >> the code in my other LaTeX documents :-) > > These days, it is hard to imagine why anyone would have code in > anything besides a lstlisting environment, for sure. In the future > that might change. Yes, I agree -- it is important to be as flexible as possible. > Perhaps it would make sense to replace the > ``--use-verbatim-when-possible`` option with a > ``--literal-block-env=`` option, so one could just:: > > --literal-block-env=verbatim > > or:: > > --literal-block-env=lstlisting > > or even better, if possible:: > > --literal-block-env=lstlisting[language=Python] > > The idea is that the last would handle the option to produce:: > > \begin{lstlisting}[language=Python] > the_code = in_here > \end{lstlisting} > > This would be very flexible and forward looking. Yes, I think that sounds like an excellent plan! -- Martin Geisler VIFF (Virtual Ideal Functionality Framework) brings easy and efficient SMPC (Secure Multi-Party Computation) to Python. See: http://viff.dk/. |
From: kib2 <ki...@fr...> - 2008-02-29 16:16:38
|
I've made a GEdit plugin for translating your reSt file (with syntax highlighting) to : - HTML - LaTeX (as it has been said, it's not perfect and I would certainly prefer a listing way) - OpenOffice via Dave K. odtwriter You'll find it here : http://kib2.alwaysdata.net/GEdit/ Now, I have to try Günter's LaTeX listing addon. See you. |