[sphinx-dev] Re: Custom char for bullet list?

[Guenter Milde]

On 2012-10-28, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> How do I use custom bullet char?

> Is there a way I can give a bullet list a class -- so to assign "–" char as 
> a bullet char for a given list (and have the default bullets in other 
> lists)?

> I need it to cite dialogs:

> -- The next time I tell You that I saw something -- You believe me!
> -- Oh, relax -- now that we saw Dracula, the Wolfman and a Monster -- 
> there's nobody to fright us anymore. *(and the Invisible man in the rostrum

You can use the reSt `class`_ directive. In Sphinx, "class" may be
overwritten by another directive (for documenting classes in OO programms)
and you must use the (somewhat misleading) "cssclass" alias.

.. _class: http://docutils.sourceforge.net/docs/ref/rst/directives.html#class

example::

  .. class:: dialogue

  - Good morning.
  - Hm.

Günter  



-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: .. image::. prob

[Guenter Milde]

On 2012-10-25, Renato Pontefice wrote:
> Sorry Gunter, what do you mean with:
> "Mark, that you now have an "inline" "

Images defined via ::

   .. image:: myimage.svn
   
are block-level elements (like literal blocks or quotes), while images
defined via ::

   
   .. |biohazard| image:: biohazard.png
   
   |biohazard| symbol.
   
are inline elements (like *emphasized* text or links_).

.. _links: not rechts

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: .. image::. prob

[Guenter Milde]

On 2012-10-24, Renato wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> I've solved.

> this is the code:
> ___
> The |biohazard| symbol must be used on containers used to 
> dispose of medical waste.

> .. |biohazard| image:: biohazard.png

> ___


Mark, that you now have an "inline" image (which is probably what you
want but "block level" images should work, too).

See 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#image
http://docutils.sourceforge.net/docs/user/rst/quickref.html#substitution-references-and-definitions
for details.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: .. image::. prob

[Guenter Milde]

On 2012-10-24, Renato wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi,
> I've image problems.

> with this statement:
> .. image:: /xyz/image.png

> I don' t receive neither the images, nor an error.

What do you receive instead of the image? Maybe you just forgot to put a
blank line before the directive?

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Different numbering schemes in nested ordered lists?

[Guenter Milde]

On 2012-10-12, leam hall wrote:

> [-- Type: text/plain, Encoding:  --]

> For my next trick...

> I have nested ordered lists, so that:

>  1. blah
>  2. blah
> 1. foo
> 2. bar
>  3. More blah



> I got them to indent correctly, mostly, in PDF and HTML. However, in one 
> foo is 1.1 and in the other foo is 1.a and bar is 1.b. Is there any way to 
> force specific numbering schemes? 

There are two levels of formatting the numbering scheme:

1. in the source (see the `rst documentation`__)
2. in the stylesheet(s).

__ 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#enumerated-lists

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: section number

[Guenter Milde]

On 2012-10-08, Federico Bruni wrote:
> 2012/10/8 Renato Pontefice :
>> it seems like I cant use more that 2 sign for the section marker...

> Actually, you should use a different sign for each section level.
> So in this case 3 different signs for 3 different sections, IIUC.

> But this is obvious and well documented:
> http://sphinx.pocoo.org/rest.html#sections

Not to forget the `reStructuredText primer`__
and the full `reStructuredText`__ documentation.

__ http://docutils.sourceforge.net/docs/user/rst/quickref.html
__ http://docutils.sourceforge.net/rst.html

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: extension which includes CSS

[Guenter Milde]

On 2012-09-24, Jake Vanderplas wrote:


> Thanks Günter,
> I'd thought of that, but I'd prefer this to be as easy for users as
> possible: that is, they can just load the sphinx extension, and not have to
> modify their style sheet.  Is there any way to modify what is within
> without using a custom style sheet?

While it may be possible (and maybe simpler for the user), it is certainly
much more complicated for the extension writer.

I may be missing a hook adde by Sphinx, but I assume that this can only be
achieved by a custom HTML writer/builder that overwrites the method to
combine the document parts to the final HTML document(s).

I'd prepare a CSS style sheet that imports the default style sheet and the
"ipython" style sheet and document that this should be selected in the
config file (the user will have to touch the config file anyway in order to
load the extension...)

Alternatively, you might consider customizing the HTML template(s).
I don't know whether this can be done in an extension or also requires
modification of the config file, though.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: extension which includes CSS

[Guenter Milde]

On 2012-09-23, Jake Vanderplas wrote:

> Hi,
> I'm attempting to build a sphinx extension for the inclusion of ipython
> notebooks, based on nbviewer [1].  I have a quick-and-dirty implementation
> that works in HTML by deriving from the raw directive [2].  Eventually I
> hope to write a better custom directive that supports latex output as well.

> One issue I'm having now is that the HTML rendering of the notebook uses
> CSS, so to do this correctly I need the notebook directive to cause CSS
> code to be added to the  part of the HTML document.  Is there
> a good, general way to do this within sphinx?

You can specify a custom stylesheet in the config file.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: MathML to sphinx

[Guenter Milde]

On 2012-09-16, Daniele Zambelli wrote:

> I'm writing a python programm to convert Open Document Format (ODT)
> into Sphinx (ReST), I'm trying to improve the odt2rst:
> http://code.google.com/p/odt2rst/

> I would like to manage the math equation, the ODT format for the math
> equation is the MathML standard: http://www.w3.org/TR/MathML/

> I did not found any simple way to convert from the MathML format  to
> ReST/LaTex.
> Do you know any tools that could be used to do this?
> Do you have any hint to insert MathML into Sphinx/ReST document?

The Docutils plan to support alternative input formats for `math
markup`__ With MathML one of the input formats, you would be able to just
insert the MathML source. 

The syntax will be something like::

  .. math::
 :input-format: MathML
 
 http://www.w3.org/1998/Math/MathML"; mode="display">
 
 
 N=
 number of apples
 7

However, this would only help with HTML+MathML
output, as long as there is no converter from MathML to LaTeX
(unfortunately, I don't know of a suitable one).

__ http://docutils.sourceforge.net/docs/dev/todo.html#math-markup


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How do I use xelatex to build epub?

[Guenter Milde]

On 2012-09-12, Boris Kheyfets wrote:

> I want to use epub builder with math.

> I found that mathjax currently is not supported by epub. So I swithed to 
> pngmath. 

> But it doesn't render mathjax's unicode greek letter I like to use. It 
> there a work around?

Does this mean you want to use Greek Unicode characters instead of \alpha
... \omega in the source?

> I tried to make epub builder use xelatex to build the images of formulas -- 
> but I couldn't find where the latex is called in the epub builder source 
> code.

I can't help with Sphinx formatting, but mind, that also xelatex does not
process non-ASCII characters in mathematical mode unless you also use the
package unicode-math.

OTOH, the Docutils latex writer transforms Unicode characters to their
(La)TeX equivalent in mathematical mode via the call::

  math_code = node.astext().translate(unichar2tex.uni2tex_table)

where the translation dictionary unichar2tex.uni2tex_table is defined in the
docutils.utils.math sub-package. Maybe this can be ported to the Sphinx
maths extension.

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Specifying Sphinx configuration overrides when invoking sphinx-build

[Guenter Milde]

On 2012-09-03, Simon Holywell wrote:

> I am writing a custom build script for a set of projects documented with 
> Sphinx. I want to be able to override the html_theme and html_theme_path 
> using -D arguments, but seem to be having an issue setting html_theme_path.

> The command I am running per project is the following (I have chopped the 
> file path lengths down for a little more readability):

> sphinx-build -b html -D html_theme=treffynnon -D 
> html_theme_path=/home/user/_themes /home/user/sphinx/src 
> /home/user/output/docs

> The error I am getting back when I execute the command is:

> Theme error:
> no theme named u'treffynnon' found (missing theme.conf?)

Wild guess: did you try specifying html_theme_path before html_theme?

Günter 

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Color table?

[Guenter Milde]

On 2012-09-04, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> This works, and is cool, I took the note. But this will color all the 
> tables in the document, wouldn't it?

Yes, but the tip can easily be extended to tables with a specific class
argument by making the CSS selector more specific, e.g. ::

  table.everyfourth tr:-child(4)
  
etc.

Günter  

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Align figure center and bottom?

[Guenter Milde]

On 2012-08-31, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Oh I am sorry -- I've made a wrong link to screenshoot here's a right one:
> screenshot .

> I get no warning or errors, and here's html code

...

> So there's indeed a class="align-bottom" (though I don't see how I would 
> center it also). But it doesn't work. Perphaps one should add the class to 
> css... img.aligh-bottom? td.allign-bottom?

Indeed, there is no CSS rule for align-bottom in Docutils' default style
sheet (html4css1.css). Furthermore, I don't see a way to define a rule
for image.align-bottom, as the valign (top/bottom) property should be
defined for the containing element. This means that the "image" directive
option

  :align: top/bottom
  
does not make sense with HTML output currently. (The reST specs have the
caveat: "The specific behavior depends upon the browser or rendering
software used.")

The desired output can be achieved adding a valign arg to the relevant row
(e.g. via post-processing):


 
 
 
 
 
 
 
 left captionright caption
 
 
 

A similar effect should be achievable with 

 
 
and a CSS rule for ``tr.align-bottom``. However, reST does not offer a
way to pass class arguments to table columns, rows, or cells.

If all rows can be bottom (instead of top) aligned, you might give a class
to the whole table and define a rule for ``table.align-bottom tr``.
If all rows in all tables can ... you don't even need a class for the table.
You might need a more specific CSS selector to override the top alginment,
though.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Align figure center and bottom?

[Guenter Milde]

On 2012-08-28, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Doesn't work:

> .. |left-image| image:: _static/SuperCompArch.jpg
>   :width: 80%
>   :alt: Supercomputer archeticture
>   :align: bottom

> .. |right-image| image:: _static/ClustArch.jpg
>   :width: 80%
>   :alt: Cluster archeticture
>   :align: bottom

>  =
>|left-image|  |right-image|

> left caption  right caption
>  =

> screenshot <http://farm9.staticflickr.com/8434/7879097568_94e652749f_s.jpg>


If I interpret the screenshot right, the problem is that the left caption is
missing, right?

Could you have a look at the generated HTML file, whether it is already
missing there? 

Did you get warnings or errors?

How about PDF export, does it work?


Günter


> On Monday, August 27, 2012 5:40:43 PM UTC+4, Guenter Milde wrote:

>> On 2012-08-27, Boris Kheyfets wrote: 

>> > [-- Type: text/plain, Encoding: quoted-printable --] 

...

No TOFU please.


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Feature request :nowrap:/:pre-wrap: code-block directive options

[Guenter Milde]

On 2012-08-28, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Doesn't work:

> rst file:

> .. code:: python
>:class: nowrap 

>for i in range(5): test test test test test test test test test test 
> test test test test

> css file:
> I tried:

> pre.nowrap {
> white-space: nowrap;
> }

> div.nowrap {
> white-space: nowrap;
> }

> span.nowrap {
> white-space: nowrap;
> }

> none wraps the code.

If you have "nowrap" in the class argument and CSS rule, this is to be
expected... This only makes sense, if the default CSS rule for code wraps!

The point is that you should be able to distinguish between a default case
(without class argument) and a "classified" case.

Next, look in the generated HTML what elements and classes are generated
from your examples and write rules to style them. 

(In my experiments, I often temporarily add a "background: green;" or
similar line to CSS rules, so that I can see which elements are matched
by the rule.)

Hope this gets you going,

Günter





> On Monday, August 27, 2012 5:31:40 PM UTC+4, Guenter Milde wrote:

>> On 2012-08-27, Boris Kheyfets wrote: 

>> > [-- Type: text/plain, Encoding:  --] 

>> > I wont to cite code word-wraped in code-block. I can turn on the line 
>> > numbers to preserve the integrity. This can be done by adding 

>> > white-space: pre-wrap; 

>> > to pre in css. 

>> > However sometimes I cite csv files -- and I don't want them to wrapped. 

>> > It would be nice to have :nowrap: and :pre-wrap: options of code block. 

>> > Do You think I can currently emulate this option -- that is to have pre 
>> > wrapped at one parts of rst file, and no-wraped in other parts? (while 
>> both 
>> > in code-block) 

>> You can always add a class argument, either via:: 

>>.. code::   
>>   :class: wrapped 

>>   code that wraps in language  

>> The "class" directive option can also be given to the "include" directive 
>> (e.g. for included cvs files):: 

>>.. include myfile.cvs 
>>   :code: text 
>>   :class: nowrap 

>> A literal block, can be preceded with a "class" directive:: 

>>Now some literal block: 

>>.. class:: wrapped 

>>:: 

>>   literal block with the "wrapped" class 

>> See http://docutils.sourceforge.net/docs/ref/rst/directives.htmlespecially 
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#class 
>> for details. 

>> I'd style the default to use the more often required wrapping mode and 
>> use either "wrap" or "nowrap" class argument (with another rule in the 
>> custom CSS sheet) for the exceptions. 

>> Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Figure caption?

[Guenter Milde]

On 2012-08-28, Boris Kheyfets wrote:

>> Is it somehow possible to have a figure caption different form the text of 
>> the link to that figure?

> Oh I found it:

> See :ref:`link title `.

> .. _figure:

> .. figure:: _static/UnixFileSystem.jpg
>:width: 50%
>:alt: Unix file system
>:align: center
>:name: test name

>Figure caption


The "name" argument should make the preceding target
redundant, try::


See :ref:`link title `.

.. figure:: _static/UnixFileSystem.jpg
   :width: 50%
   :alt: Unix file system
   :align: center
   :name: figure

   Figure caption


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Align figure center and bottom?

[Guenter Milde]

On 2012-08-27, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Thanks Gunter.

> I tried:

> ++---+
>|.. _SuperCompArch:  |.. 
> _ClustArch: |

>|   |
>|.. image:: _static/SuperCompArch.jpg|.. image:: 
> _static/ClustArch.jpg   |
>|   :width: 80%  |   :width: 
> 80% |
>|   :alt: Supercomputer archeticture |   :alt: Cluster 
> archeticture  |
>|   :align: bottom   |   :align: 
> bottom  |

>|   |
>|Super computer archeticture |Cluster 
> archticture|
> ++---+

> but it gives:

> /home/boris/pst/wordy/edu/HighestProgramming/00_-_intro.rst:484: ERROR: 
> Error in "image" directive: "bottom" is not a valid value for the "align" 
> option.  Valid values for "align" are: "left", "center", "right".
> /home/boris/pst/wordy/edu/HighestProgramming/00_-_intro.rst:484: ERROR: 
> Error in "image" directive: "bottom" is not a valid value for the "align" 
> option.  Valid values for "align" are: "left", "center", "right".

You still use block-level images.

>> which means you need to define your images as inline,

*outside of the table*, via a substitution definition 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#substitution-definitions
e.g.

>> .. |left-image| 
>> .. image:: _static/SuperCompArch.jpg 
>>:width: 80% 
>>:alt: Supercomputer archeticture 
>>:align: bottom 

>> and use the tag(s) in the table 

>>   ===   
>>   |left-image| |right-image| 

>>   left caption right caption 
>>   ===   

(this is a simple table syntax, the | are not table lines but
mark substitutions).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Underline inline markup?

[Guenter Milde]

On 2012-08-27, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Hello Gunter

> I tried:

> .. _doc:

> .. role:: underlined(raw)
>:format: html
>:style: text-decoration: underline;

This creates a role based on the raw role, i.e. it expects the content to be
raw html.

Instead, write

.. role:: underlined

and a CSS rule to style ``span.underlined`` in a custom style sheet.


Suggestions/patches improving
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
>>  
to make this more clear are welcome.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Feature request :nowrap:/:pre-wrap: code-block directive options

[Guenter Milde]

On 2012-08-27, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> I wont to cite code word-wraped in code-block. I can turn on the line 
> numbers to preserve the integrity. This can be done by adding

> white-space: pre-wrap;

> to pre in css.

> However sometimes I cite csv files -- and I don't want them to wrapped. 

> It would be nice to have :nowrap: and :pre-wrap: options of code block.

> Do You think I can currently emulate this option -- that is to have pre 
> wrapped at one parts of rst file, and no-wraped in other parts? (while both 
> in code-block)

You can always add a class argument, either via::

   .. code::  
  :class: wrapped
  
  code that wraps in language 

The "class" directive option can also be given to the "include" directive
(e.g. for included cvs files)::

   .. include myfile.cvs
  :code: text
  :class: nowrap

A literal block, can be preceded with a "class" directive::
  
   Now some literal block:

   .. class:: wrapped
   
   ::
   
  literal block with the "wrapped" class
  
See http://docutils.sourceforge.net/docs/ref/rst/directives.html especially
http://docutils.sourceforge.net/docs/ref/rst/directives.html#class
for details.
  
I'd style the default to use the more often required wrapping mode and
use either "wrap" or "nowrap" class argument (with another rule in the
custom CSS sheet) for the exceptions.

Günter
  


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Looking for literal block that supports inline directives

[Guenter Milde]

On 2012-08-23, m...@mikesolomon.org wrote:
> Hey all,

> I know that parsed-literal is a literal block that supports inline
> markups, but is there a literal block that supports inline directives?

All reST directives are block-level elements, but only inline-markup is
parsed in a parsed-literal block
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

There is no literal block variant that supports nested directives.

> Specifically, I need to do something like:

> .. parsed-literal::
>   .. raw:: html
>  :file: test.html

Even if the raw directive were parsed, the content would be included
"as-is", without any processing by Docutils and only if the output format
is HTML. This will not work for the display of HTML source code.

> The goal is for the contents of test.html are displayed in literal
> typeset. Of course, I could copy and paste the contents of test.html
> in a literal block, but test.html will change a lot and multiple people
> will be working on it, so it'd be better to use the contents of the
> file itself.

With Docutils >= 0.9, you can achieve this (without parsing of
rst-inline-markup in the HTML file) with the "include" directive::

  .. include:: test.html
 :code: HTML

http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

To pass the content of the included file to a "parsed literal" block, a new
option for the "include" directive would be required. Then you could write

  .. include:: test.html
 :parsed-literal: HTML

If you think this would help you (and others), you may file an enhancement
request at the Docutils tracker
http://sourceforge.net/tracker/?group_id=38414

As a workaround, you may consider inserting the html file into the
parsed-literal block with a helper script before the sphinx run.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Underline inline markup?

[Guenter Milde]

On 2012-08-20, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> Is it somehow possible to have an underline inline markup? I know I can use 
>:title: -- but it's somehow crooked way of getting things underlined.

Use a custom role and style it with CSS and/or in the LaTeX preamble.

See 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Align figure center and bottom?

[Guenter Milde]

On 2012-08-20, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> I have two figure in a table:

> ++---+
>|.. _SuperCompArch:  |.. 
> _ClustArch: |

>|   |
>|.. figure:: _static/SuperCompArch.jpg   |.. figure:: 
> _static/ClustArch.jpg  |
>|   :width: 80%  |   :width: 
> 80% |
>|   :alt: Supercomputer archeticture |   :alt: Cluster 
> archeticture  |
>|   :align: center   |   :align: 
> center  |

>|   |
>|   Super computer archeticture  |   Cluster 
> archticture |
> ++---+

> but they are of different heigh. And I would like them to be sticked to the 
> bottom of the table. In other words I want them to be centerd and bottomed 
> in the same time.

> I've read the docs, but it looks like `figure`  doesn't have `bottom` 
> option at all.

There are two image directives: "image" and "figure".
If you don't need a caption and legend, use "image".

See http://docutils.sourceforge.net/docs/ref/rst/directives.html#images

There you also see:

align : "top", "middle", "bottom", "left", "center", or "right"
The alignment of the image, equivalent to the HTML  tag's
"align" attribute. The values "top", "middle", and "bottom" control
an image's vertical alignment (relative to the text baseline); they
are only useful for inline images (substitutions). The values "left",
"center", and "right" control an image's horizontal alignment,
allowing the image to float and have the text flow around it. The
specific behavior depends upon the browser or rendering software
used.

which means you need to define your images as inline, e.g. via

.. |left-image| 
.. image:: _static/SuperCompArch.jpg
   :width: 80%
   :alt: Supercomputer archeticture
   :align: bottom
   
and use the tag(s) in the table

  ===  
  |left-image| |right-image|

  left caption right caption
  ===  
  
Günter  

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Word-wrap in code-block?

[Guenter Milde]

On 2012-08-18, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> Thanks. It works. I wonder if it is possible for latexpdf also.

Not out of the box.
You might try with the listings package (relatively easy in Docutils, but I
don't know whether/how possible in Sphinx).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How to avoid text floating around images?

[Guenter Milde]

On 2012-08-17, helix wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi folks, 

> the subject says it all.

> I use html output with sphinx and the text following an image is floating 
> around it. 
> How can I avoid that?

This behaviour is controled by CSS rules. 
You can change it in a custom CSS sheet.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: In line syntax highlighting?

[Guenter Milde]

On 2012-08-18, Boris Kheyfets wrote:

> [-- Type: text/plain, Encoding:  --]

> Is somehow possible to highlight a piece of text in line in a given 
> language (with pygments)?

> Something like this:

> Some text :myLanguage:`from i to j; do` some more text.

Yes, there is the :code: role for this since Docutils 0.8. In order to
highlight a language, you must define a custom role 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
based on "code".

Example from the "standard.txt" test file:

  For inline code snippets, there is the `code` role, which can be used
  directly (the code will not be parsed/tagged, as the language is not
  known) or as base for special code roles, e.g.,
  
  .. role:: tex(code)
 :language: latex
  
  
  Docutils uses LaTeX syntax for math directives and roles:
  :tex:`\alpha = f(x)` prints :math:`\alpha = f(x)`.

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How to write unbalanced paretheses in literal text?

[Guenter Milde]

On 2012-08-18, Aivar Annamaa wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi!

> I'm trying to write an inline code sample with a syntax error in it: ``x = 
> 3 + (4 * 5 ``, but I get error "Inline literal start-string without 
> end-string". If I close the parens, then the error goes away.

This is not about the parenthesis but the space before the end-string.

Is there a space before the end-string in your sample, too?

Does it work with ``x = 4 + (3 * 5``?

For reference: Does it work with ``x = 4 + (3 * 5) ``?

In order to minimize false positives, there are quite elaborated rules for
recognition of rST role start- and end-strings. See 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup-recognition-rules

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Use other verbatim environments

[Guenter Milde]

On 2012-07-06, Jose Gomez-Dans wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi,

> I am including a lot of files that are basically long plain ascii files.
> fancyvrb doesn't allow line breaking on a long space (like spverbatim
> does). Ideally, you should get a symbol showing you that the line continues
> (like they do in the O'Reilly books ;-D)

> Is there a simple solution to this, apart from going around changing all
> Verbatim calls in sphinx to something else?

I don't think so (except for a script doing all the changes).

In Docutils, there is a setting to specify the environment used for
literal blocks in LaTeX. See literal_block_env at
http://docutils.sourceforge.net/docs/user/config.html#latex2e-writer (I
recommend the highly configurable "lstlisting" from the "listings"
package.) 

You may file an enhancement report for Sphinx.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: how to show ''' (triple-single quote)?

[Guenter Milde]

On 2012-07-04, Kevin Hunter wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> At 2:49pm -0400 Wed, 04 Jul 2012, Günter Milde wrote:
>> On 2012-07-04, Kevin Hunter wrote:
>>> I think the issue is LaTeX interpreting it,
>> ...

>> Yes, if it affects only the latexpdf output, maybe it is not the
>> beautifier. Can you post what ``'''`` looks like in the LaTeX source?

>> The Docutils latex writer translates it to ::

>> \texttt{'{}'{}'}

>> But Sphinx uses it's own fork...

> Given the attached, it appears to me that Sphinx didn't think of this 
> particular detail.

Could you file a bug report, please?

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: how to show ''' (triple-single quote)?

[Guenter Milde]

On 2012-07-04, Kevin Hunter wrote:
> At 3:52am -0400 Sun, 01 Jul 2012, Guenter Milde wrote:
>> On 2012-06-28, Kevin Hunter wrote:
>>> ReST input  Output
>>> --  --
>>> ``'''``  "'
>>> ``\'''``,\"'
>>> ``'\''``,'\",
>>> ``''\'``,"\',
>>> ``'``\ ``'``\ ``'``  '''

>> It seems like the "beautifier" uses typographic quotes ('' -> “) even in
>> inline literals. This is either some setup problem at your site or a
>> Sphinx bug. Try to disable the quote conversion.

> I actually appreciate the beautifier, and it's only for the latexpdf 
> output. 

> I think the issue is LaTeX interpreting it, 
...

Yes, if it affects only the latexpdf output, maybe it is not the
beautifier. Can you post what ``'''`` looks like in the LaTeX source?

The Docutils latex writer translates it to ::

   \texttt{'{}'{}'}

With 

# Break up input ligatures e.g. '--' to '-{}-'.
if not self.is_xetex: # Not required with xetex/luatex
separate_chars = '-'
# In monospace-font, we also separate ',,', '``' and "''" and some
# other characters which can't occur in non-literal text.
if self.literal:
separate_chars += ',`\'"<>'
for char in separate_chars * 2:
# Do it twice ("* 2") because otherwise we would replace
# '---' by '-{}--'.
text = text.replace(char + char, char + '{}' + char)


in LaTeXTranslator.encode().

But Sphinx uses it's own fork...

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: how to show ''' (triple-single quote)?

[Guenter Milde]

On 2012-06-28, Kevin Hunter wrote:
> Hi Sphinx Group,

> I'm trying to show an inline code example of a triple single quote. 
> I've tried a number of iterations, but can't seem to find the magic 
> incantation.  Here's some of what I've tried so far:


> ReST input  Output
> --  --
> ``'''``  "'
> ``\'''``,\"'
> ``'\''``,'\",
> ``''\'``,"\',
> ``'``\ ``'``\ ``'``  '''

It seems like the "beautifier" uses typographic quotes ('' -> “) even in
inline literals. This is either some setup problem at your site or a
Sphinx bug. Try to disable the quote conversion.


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: styles for root and normal user shell command

[Guenter Milde]

On 2012-06-13, Federico Bruni wrote:
> Il 13/06/2012 09:25, Guenter Milde ha scritto:
>> On 2012-06-12, Federico Bruni wrote:
>>> Il 12/06/2012 11:31, Guenter Milde ha scritto:

>>>>  (The "code" directive is new in reStructuredText (docutils 0.9
>>>>  (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
>>>>  Docutils versions.)


>>> Did you really mean "sourcecode"?

>> No. In Sphinx it is "source-block". Sorry for mixing it up.

>> Günter


> Sorry, you were right: I didn't specify an argument.
> In Sphinx it's called code-block and sourcecode is its alias:

> http://sphinx.pocoo.org/markup/code.html

> I think this link is quite hidden in the documentation.
> Well, it's in the index, but the first link that one will check is 
> probably this one:

> http://sphinx.pocoo.org/rest.html#source-code

Actually, the section title is incorrect: the `literal block`_ in
reStructuredText_ is not a "Source Code" element but a generic
block-level element (like the  HTML element).

  The literal_block element contains a block of text where line breaks
  and whitespace are significant and must be preserved. literal_block
  elements are commonly used for program listings and
  interactive computer sessions. 

  -- http://docutils.sourceforge.net/docs/ref/doctree.html#literal-block

.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _literal block: 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#literal-blocks

Highlight of literal blocks (and the implied notation that literal blocks
are source code by default) is a Sphinx extension. Hence, a link to
markup/code.html is in place.

> Why don't you add there a link to markup/code.html?

Because I am not a Sphinx developer.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: styles for root and normal user shell command

[Guenter Milde]

On 2012-06-13, Federico Bruni wrote:
> Il 13/06/2012 21:18, Federico Bruni ha scritto:
>> I see: I think I'll end up using a general style for shell prompt and
>> use 'sudo' to show the commands which need root privileges.
>> Thinking twice, it's better, because quite often a single code block
>> might include root and normal user commands.

>> So I guess my CSS style will be something like this:

>> .code.sh pre {
>>  background-color: #000;
>>  color: #EDEDED;
>>  font-family: Courier;
>> }

> Thinking twice again.. using for any bash command:

> .. code:: sh

> is not handy at all.
> I'd rather use the literal block and specify the highlight I want in the 
> conf.py or in the beginning of the document:

> .. highlight:: sh

> Which means the CSS class to override will be:

> .highlight-sh pre {background: #000}


Indeed. Looking at the generated HTML, if find two levels of divs::

  
   ...
  
  

instead of the simple . 
May be worth a bug report.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: auto numbering and figures

[Guenter Milde]

On 2012-06-13, SFL wrote:

> I would like to combine documents dynamically, therefore I intend to use 
> the automatic numbering feature. However,
> including figures seems to break the numbering. All topics will start with 
> "1" instead of continuous counting steps. 

Any element other than the next list item closes the enumeration.
You may nest most elements (no section headers) in the list instead::

  #. In the **New Example** dialog, select **Standalone Sample Project**, 
 then click **Next**.
  
 .. image:: images/1215016F3E8B3EA6.png
  
 .. note:: 
 
Depending on the product features installed, the **New Example**
dialog may appear different.
  
  #. The custom flash driver template allows you to add a new flash device to 
 the Flash Programmer view. In the **New Project Sample** dialog,
 select **The custom Flash Driver Template**, then click Finish. 
  
 .. image:: images/126601B6D742F4D5.png

If you want to continue an enumeration after some other element, it is
sufficient to number the first item:

  3. The custom flash driver now appears in the project list of the
 **Project Explorer** view. 

  #. This will become item 4.


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: styles for root and normal user shell command

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:
> Il 12/06/2012 11:31, Guenter Milde ha scritto:

>> (The "code" directive is new in reStructuredText (docutils 0.9
>> (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
>> Docutils versions.)


> Did you really mean "sourcecode"?

No. In Sphinx it is "source-block". Sorry for mixing it up.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: styles for root and normal user shell command

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:
> Il 13/06/2012 00:48, Federico Bruni ha scritto:
>> Currently I have docutils 0.8 on my debian system.
>> I've tried installing latest svn version but code is not recognized:

> Nevermind, it didn't work because I followed the README in docutils 
> source code (which recommended using python3), so Sphinx didn't look in 
> /usr/local/lib/python3.2

This must be a misunderstanding. Docutils works with Python 2.3 and
newer but is less tested under Python 3. For Sphinx, you need an
installation under 2.x.

In order to use Docutils under Python 3, it needs to be set up under
Python 3, because only then the sources are converted to 3-compatible
versions.

If you want to use it under both, Python 2.x and Python 3.x, run e.g.

.. code:: sh
   
   cd 
   cd test
   python alltests.py
   cd ..
   python3 setup.py build
   cd test3
   python3 alltests.py
   cd ..

and if no critical errors turn up:

.. code:: sh
   :class: root

   cd 
   python3 setup.py install
   python setup.py install
   
(The last setup command should use the default Python version, as
distutils puts the command it was called with in the shebang line of the
executables.) 

The latter code block translates here to::

  and if no critical errors turn up:
  
  cd 
  python3 setup.py install
  python setup.py install
  

which should match a CSS rule like::

  pre.sh.root {background: red;}
  
However, prefixing some command line prompt via CSS does not work, as the
lines are not wrapped in a tag.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: styles for root and normal user shell command

[Guenter Milde]

On 2012-06-12, Federico Bruni wrote:
> Hi,

> the easiest way to enter shell commands is probably not using any $ and 
> # sign in front of the command and using sudo for commands to be run as 
> root.

> But it would be nice to handle it differently.

> I'd like to be able to define two styles for shell commands.
> I don't want to use "sudo" in the root commands.
> I'd like to enter only the real command in the literal block, with no 
> leading $ or # (because it's not handy for copy&paste).

> $ and # signs should be added by a style, that I may specify as a option 
> of the literal block.

> Something like this:

> Install the dependencies::
> :user: root
> aptitude install bla bla bla

> Run the program::
> :user: user
> python program.py


> What do you recommend to do?

a) use the "sh" lexer, give a class value to the input and use a custom
   style (CSS rule with class selector with HTML, tricky or maybe
   impossible with LaTeX/PDF)::
   
  .. code:: sh
 :class: user
 
 python program.py
 
  .. code:: sh
 :class: root
 
 python setup.py install
 
   (The "code" directive is new in reStructuredText (docutils 0.9
   (2012-05-02). Use the Sphinx extension "sourcecode" with earlier
   Docutils versions.)
  
b) Create and use Pygments lexers, e.g. "shell-user" vs. "shell-root" (or
   just use the existing "sh" lexer). See
   http://pygments.org/docs/lexers/#lexers-for-various-shells and
   http://pygments.org/docs/lexerdevelopment/

> Also, how can I style the shell commands differently from other literal 
> blocks?

Either use the "code" directive, ::

  .. code:: sh
  
 ls -l

or set the "default literal block style":

  The highlighting language can be changed using the highlight directive,
  used as follows::

.. highlight:: c

  This language is used until the next highlight directive is
  encountered.

  -- http://sphinx.pocoo.org/markup/code.html

  
Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Clickable field list labels

[Guenter Milde]

On 2012-06-03, Roger Binns wrote:

> I have a bunch of data presented using field lists like this (dummy labels
> and data):

>  :Validity: 37.2
>  :Duration: 17 of 6

> I'd like to provide a way of linking to another ref which has detailed
> explanations of what each label means and how it was calculated.  A simple
> approach is to include it with the value like this:

>:Validity: 37.2 :ref:`(i) `

> Unfortunately that is rather ugly and litters the page.  I can use
> Javascript and CSS to make the label clickable but that doesn't help with PDF.

> Any suggestions?  I'm very reluctant to abandon field lists as they work
> extremely well for my documents.

Just use the standard reStructuredText link syntax
http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets
e.g. ::

  Field list _`label` with normal link:

  :label_: just a test



Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Referencing options when .. program:: is used, ~ does not work as expected

[Guenter Milde]

On 2012-05-30, Michael Schlenker wrote:
> Hello,

> i tried to cross reference some option when program contexts are used.

> Contrary to the documentation
> (http://sphinx.pocoo.org/markup/inline.html#xref-syntax) it is not
> currently possible to suppress the
> program name when referencing.

> Example:

> .. program:: foo

> .. option:: -baz

>The baz option.

> .. program:: bar

> .. option:: -baz

> When using :program:`foo`, you can use :option:`~foo -baz` to ...

> I would have expected that this creates '-baz' with a link to the
> correct option, instead it writes `~foo -baz`, e.g no link at all.

> Is this a bug (e.g. should this work), or a missing feature?

Maybe you need to nest the options?

.. program:: foo

  .. option:: -baz
  
 The baz option.

.. program:: bar

  .. option:: -baz


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Using Sphinx to document configuration files in e.g. JSON, YAML, etc?

[Guenter Milde]

On 2012-05-17, Ramon wrote:

> We are defining an integration SDK that includes some fairly involved 
> parameter files, currently formatted in YAML syntax. I’d like to provide 
> “sample code” for these configurations (i.e. sample configuration files) as 
> well as detailed technical documentation on the format requirements (data 
> type constraints, etc). We are not wed to the YAML format yet, so if 
> another roughly equivalent format (e.g. JSON) is well-supported in Sphinx 
> we’d consider switching as getting the documentation in good shape to 
> encourage adoption by developers is a key goal.

> Are there any Sphinx approaches for documenting data structures or 
> parameter / configuration files like this? 

The PyLit bidirectional text/code converter can be used for "literate config
files" in any config file syntax with documentation in reStructuredText.
Pylit will convert the file from rst with code snippets to code with
extensive comments and back. For an example config file, see
http://pylit.berlios.de/conf.py.html

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: wrap text around image

[Guenter Milde]

On 2012-05-06, Gour wrote:
> On Sun, 6 May 2012 15:24:53 + (UTC)
> Guenter Milde  wrote:

>> It works on HTML using CSS rules (Docutils feature). 

> Yeah, that's expected.

>> Docutils LaTeX writer does currently not support text around figures -
>> this is a TODO issue. 

> Thank you. For how long it's on the TODO list?

Some years, AFAIK. Rather low priority.

> Edit: I noticed that the list is updated on 2012-02-27.

>> I don't know about Sphinx.

> Afaict, it does not support it as well which leads us to simply use
> LyX/LaTeX.

I read this on the lyx users list.

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: wrap text around image

[Guenter Milde]

On 2012-05-05, Gour wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Hello!

> I got reply on rst2pdf list that rst2pdf cannot wrap text around
> (floating) images due to limitation in reportlab.

> Considering it's one of the features we're not happy about with
> AsciiDoc, I wonder what is in Sphinx the procedure to wrap text around
> floating images (left or right) for both HTML/PDF output? 

It works on HTML using CSS rules (Docutils feature). Docutils LaTeX writer
does currently not support text around figures - this is a TODO issue.
I don't know about Sphinx.

The reStructuredText syntax is described in 
http://docutils.sourceforge.net/docs/ref/rst/directives.html#image and
http://docutils.sourceforge.net/docs/ref/rst/directives.html#figure

Example::

  .. image:: picture.jpeg
 :width: 200 px
 :align: right
 
Günter 

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: mixing fonts or reST/Sphinx vs. AsciiDoc

[Guenter Milde]

On 2012-05-04, Gour wrote:
> On Wed, 28 Mar 2012 11:46:06 + (UTC)
> Guenter Milde  wrote:

> Excuse me for late reply...I was playing a bit with AsciiDoc and had
> some other tasks in the meantime...

>> On the input side, reStructuredText allows both, direct input as
>> Unicode character as well as via substitution definitions like ::

>>   .. |copy| unicode:: 0xA9 .. copyright sign

>>   Copyright |copy| 2012

> OK. Thank you.


>> PDF output requires configuring LaTeX via packages and preamble code.
>> The details depend ou your choice between traditional 8-bit TeX and
>> XeTeX or LuaTeX as back-end.

> I bet that using XeTex/LuaTeX is no problem...at least, XeTeX is
> standard part of my TexLive package.

I don't know whether XeTeX/LuaTeX output is supported by Sphinx. With
Docutils, you can use the "XeTeX" writer via the rst2xetex backend. For a
single document, this would be:

  rst2xetex mydoc.txt > mydoc.tex
  xelatex mydoc.tex

Font configuration would be done in the LaTeX preamble. See the "fontspec"
package documentation for details how to use different fonts for different
Unicode ranges.


With "normal" LaTeX, you should look up the required symbols in 
`The Comprehensive LaTeX Symbol List`__ or (if it's a math symbol)
`Unicode symbols and corresponding LaTeX math mode commands`__

__ http://mirror.ctan.org/info/symbols/comprehensive/symbols-a4.pdf
__ http://milde.users.sourceforge.net/LUCR/Math/unimathsymbols.xhtml

The latter shows for the sun symbol '☉' (9737, 0x2609) SUN
that it is provided by package "mathabx" under the name ``\Sun``.

The following preamble code sets this up, if the output-encoding is "utf8"::

  \usepackage{mathabx}
  \DeclareUnicodeCharacter{2609}{\ensuremath\Sun}  % ☉


>> HTML output should work out of the box with a modern browser that does
>> the font substitution automatically.

> OK, but I'm curious how to mix fonts...for instance I've special font
> containing glyphs for planets & other astrological symbols and it
> provides such mapping that in my AsciiDoc file I can define something
> like:

>:sun: a

> and then use it, similar to the above, like:

> Symbol for the Sun is +{sun}+.

> The trick is that the text enclosed in '+' characters (e.g. +{sun}+) are
> rendered in monospaced font.

1. Try whether the browser displays the symbold out of the box

2. To select a special font, put the part in a custom role, e.g. ::

 .. role:: astro

 This :astro:`☉` is the Unicode symbol sun.

and create a custom CSS sheet with a rule like::

span.astro {font: mono;}

(How to use this stylesheet differs in Docutils and Sphinx, see the
respective documentation.)

2a. For display with a monospaced font, you can also use the "literal"
role with the literal Unicode char::

   This ``☉`` is the Unicode symbol sun.

No other setup required (if the default monospaced font suffices).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Docutils 0.9

[Guenter Milde]

On 2012-05-02, Werner wrote:
> On 02/05/2012 21:17, Guenter Milde wrote:
>> On 2012-05-02, Werner wrote:
>>> On 02/05/2012 10:26, Guenter Milde wrote:
>>>> Dear Sphinxers,
>>>> the Docutils team is going to release Docutils v. 0.9.
>>> Didn't see the PIL import issue mentioned, will this be fixed in this
>>> release?
>>> https://bitbucket.org/birkenfeld/sphinx/issue/757/again-accessinit-hash-collision-3-for-both
>> I don't think so (but there are more bugfixes in v. 0.9 than mentioned in
>> the last mail).

>> If this is a Docutils issue, you might file a bug report to the
>> Docutils bug tracker 
>> http://sourceforge.net/tracker/?group_id=38414&atid=422030
> There is already one:
> http://sourceforge.net/tracker/?func=detail&aid=2993756&group_id=38414&atid=422030

> It seems that "goodger" doesn't want to fix it and I am not technical 
> enough to argue the point.

It is fixed since Dec 2011 and now also documented.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Docutils 0.9

[Guenter Milde]

On 2012-05-02, Werner wrote:
> On 02/05/2012 10:26, Guenter Milde wrote:
>> Dear Sphinxers,

>> the Docutils team is going to release Docutils v. 0.9.
> Didn't see the PIL import issue mentioned, will this be fixed in this 
> release?
> https://bitbucket.org/birkenfeld/sphinx/issue/757/again-accessinit-hash-collision-3-for-both

I don't think so (but there are more bugfixes in v. 0.9 than mentioned in
the last mail). 

If this is a Docutils issue, you might file a bug report to the
Docutils bug tracker http://sourceforge.net/tracker/?group_id=38414&atid=422030

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Docutils 0.9

[Guenter Milde]

Dear Sphinxers,

the Docutils team is going to release Docutils v. 0.9.

It would be nice if people could test their setup and extensions with the
repository__ version or snapshot__ for eventual compatibilty problems.

__ http://docutils.sourceforge.net/docs/dev/repository.html
__ http://docutils.svn.sourceforge.net/viewvc/docutils/trunk/docutils/?view=tar


Günter


>From the HISTORY.txt and RELEASE_NOTES.txt files:

Future changes
==

* docutils/math, docutils/error_reporting.py, and
  docutils/urischemes.py will move to the utils package
  Code importing these modules needs to adapt, e.g.::

try:
import docutils.math as math
except ImportError:
import docutils.utils.math as math

* docutils.io.FileInput/FileOutput will no longer do a
  system-exit on IOError by default.

  Roadmap:

  :0.10: change of default behaviour to the equivalent of
 ``handle_io_errors=False``,
 ignore and deprecate the `handle_io_errors` option.
 (allows us to clean up Docutils code and remove the error handling
  code from the FileInput/FileOutput classes)
  :0.10 + n:   deprecation warning to stderr if FileInput/FileOutput
   is called with `handle_io_errors`,
  :0.10 + n+1: remove the `handle_io_errors` option.


Release 0.9 (unpublished)
=

* General:

  - reStructuredText "code" role and directive with syntax highlighting
by Pygments_.
  - "code" option of the "include" directive.

  .. _Pygments: http://pygments.org/

* docutils/utils.py -> docutils/utils/__init__.py

  - docutils.utils is now a package (providing a place for sub-modules)
  - DependencyList uses io.FileOutput and 'utf8' encoding to prevent
errors recording non-ASCII filenames (fixes [ 3434355 ]).

* docutils/io.py, docutils/core.py:

  - No "hard" system exit on file IO errors: catch and report them in
`Publisher.reportException` instead. Allows handling by a calling
application if the configuration setting `traceback` is True.
  - New exceptions InputError and OutputError for IO errors in
FileInput/FileOutput.

* docutils/writers/html4css1/__init__.py

  - change default for `math-output` setting to MathJax

* docutils/parsers/rst/states.py

  - Fix [ 3402314 ] allow non-ASCII whitespace, punctuation
characters and "international" quotes around inline markup.
  - Use `field_marker` pattern to look for start of a
directive option block (fixes [ 3484857 ]).

* docutils/writers/latex2e/__init__.py

  - Record only files required to generate the LaTeX source as dependencies.
  - Use ``\setcounter{secnumdepth}{0}`` instead of ``*``-versions
when suppressing LaTeX section numbering.

* docutils/writers/docutils_xml.py

  - Use the visitor pattern with default_visit()/default_depart() methods
instead of minidom to facilitate special handling of selected nodes.
  - Support raw XML (inserted as-is inside a  node).


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: list-table, header has extra new line

[Guenter Milde]

On 2012-04-19, helix wrote:
> Hi folks,

> when I use a list-table to generate a table that has headers with line
> blocks, a blank line seems to be added.

If you look at the HTML source, you will realize that there is no blank
line. Instead, the line block is wrapped in a div element:

  
  info
  warn
  error
  
  

> Can I avoid that somehow?

You can, e.g., use a custom stylesheet and override the margins for
div.line-block (or, better, just for div.line-block nested in th).


> BTW, how about a
>:align: left right center
> for list-tables?

As list tables are an upstream feature from Docutils, you might propose
this at the docutils-users list or the docutils tracker
http://sourceforge.net/tracker/?group_id=38414&atid=422033

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Directive for Custom Structured Content

[Guenter Milde]

On 2012-04-14, Tom Willis wrote:

> I have a fairly involved question that I'm looking for advice on. I posted 
> this on stackoverflow but I don't know what the action is like for 
> questions regarding sphinx in docutils. 

(Its the other way round: Docutils is the core, used programatically by
Sphinx.)

> I would like to code up a directive/extension so that I can render some 
> custom structured content.

...

> I guess I have 2 challenges.

>1. how would I take the image option and render it as an image node?(not 
>sure if that's the correct terminology)
>2. how would I get the rendered representation of the content?

See how this is done by the image and figure directives in the Docutils
source.

> I've read through the extension tutorial(
> http://sphinx.pocoo.org/ext/tutorial.html) but what I want to do seems a 
> little more involved than what's covered there.

The Docutils documentation for custom directives might be the right place to
start: http://docutils.sourceforge.net/docs/howto/rst-directives.html

You will still need the Sphinx extension tutorial to find out how
to activate your extensions in Sphinx.


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: csv-table span multiple columns

[Guenter Milde]

On 2012-04-16, Austin Godber wrote:

> [-- Type: text/plain, Encoding:  --]

> Does anyone know offhand if multiple columns can be spanned with a header 
> using the csv-table directive?

I don't think it is possible.
See the "official" description
http://docutils.sourceforge.net/docs/ref/rst/directives.html#id2

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Width of columns in Sphinx tables

[Guenter Milde]

On 2012-04-08, Nathann Cohen wrote:

> I have a small problem with simple tables... I have in my file many simple
> tables following each other, all of them on two columns, and I would like
> that their column all have the same width. The current result really is not
> pretty :-)

...

> The other thing I have to mention is that my table are pretty badly
> displayed in html, and that is because the first column take almost the
> whole page, even though it is the one which contains the less text. The
> reason ? The first column only contains links :

...

>:meth:`~Graph.vertex_cover` Returns a minimum  vertex cover of self

...


> It has to be the largest column, of I could never make
> ":meth:`~Graph" fit, but the text that ends up being displayed in
> the html file is "only" 'independent_set_of_representatives'. And this
> takes most of the page's width, because in the rest file the first
> column HAS to be the widest to fit the links.

> Well, all in all I would be delighted if there was a magic way to define
> the width of my cells in the html result. That would solve everything but I
> did not find that yet. Except for csv-tables, but then the real text file
> becomes harder to read too ^^;

Why don't you use a `list table`__?

Günter

__ http://docutils.sourceforge.net/docs/ref/rst/directives.html#list-table


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: mixing fonts or reST/Sphinx vs. AsciiDoc

[Guenter Milde]

On 2012-03-26, Gour wrote:

> I'm considering which markup to use for our open-source project to write
> user's manuals as well as for general writing (study notes etc.)

I recommend to use Docutils_ for single documents (study notes etc.) and
Sphinx for projects (web sites, software documentation). (Sphinx builds on
Docutils, both use reStructuredText_ as markup language.)

.. _Docutils: http://www.docutils.sf.net
.. _reStructuredText: http://docutils.sf.net/docs/ref/rst/restructuredtext.html

> I've played with AsciiDoc  for a few days and I like its HTML output as
> well as PDF generated via dblatex.

> However, having the need to use different symbols like planet's signs
> etc. I had some problems finding Unicode fonts having all the required
> glyphs and wondered how to easily use 'standard' Unicode font for normal
> text and then switch to the specific font containing all the required
> glyphs for rendering planet symbols.

> In AsciiDoc I use something like:

>:sun: ☉
>:moon: ☽ etc. which are then used as {sun} in the text.

On the input side, reStructuredText allows both, direct input as Unicode
character as well as via substitution definitions like ::

  .. |copy| unicode:: 0xA9 .. copyright sign

  Copyright |copy| 2012

> Now I wonder if reST/sphinx provides some simpler method of using
> specific font for rendering planet's symbols and the regular font for
> the rest?

> I mean simpler than the need to fiddle with XSL stylesheets to configure
> Docbook toolchain (dblatex) to render stuff as desired?

> Let me say that we are on Linux platform and mostly care for HTML/PDF
> outputs.

This depends on your understanding of "simpler": 

PDF output requires configuring LaTeX via packages and preamble code. The
details depend ou your choice between traditional 8-bit TeX and XeTeX or
LuaTeX as back-end.

HTML output should work out of the box with a modern browser that does
the font substitution automatically.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: literalinclude and line wrapping in Latex

[Guenter Milde]

On 2012-02-13, Jose Gomez-Dans wrote:
> On 11 February 2012 20:10, Guenter Milde  wrote:

>> On 2012-02-11, Jose Gomez-Dans wrote:

>> >> But this just changes the font, and does not affect line wrapping.
>> >> Or am I missing something?

>> The idea is to use a narrower font, as the default (both, courier and CM)
>> are rather wide. In some cases this already removes the need to wrap lines.

> This won't work here, as some of these lines are rather long (easily 400
> characters), so they'll need to be wrapped (or we start using A0 for our
> manuals!) :-D 

I see.

> I can edit the stuff in Verbatim environments to use listings, but this
> is just a manual hack to produce a quick version. Ideally, I'd like
> sphinx to take care of that.

For fixing this in Sphinx, there are several options:

a) As a quick fix, overwrite the
   visit_literal_block/depart_literal_block methods in the latex writer
   to use listings.

b) As a medium fix, port the "literal_block_env" setting
   and its handling from the Docutils latex writer
   (docutils/docutils/writers/latex2e/__init__.py) to the Sphinx latex writer.
   
c) As a proper fix, let Sphinx use the Docutils latex writer (just like it
   does use the Docutils html writer).
   
Of course, you can also file a bug report instead of doing it yourself.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: literalinclude and line wrapping in Latex

[Guenter Milde]

On 2012-02-11, Jose Gomez-Dans wrote:


>> Another option is to define a different "teletype" font in the LaTeX
>> preamble, e.g. with

>>  \renewcommand{\ttdefault}{txtt}

>> But this just changes the font, and does not affect line wrapping. Or am I
> missing something?

The idea is to use a narrower font, as the default (both, courier and CM)
are rather wide. In some cases this already removes the need to wrap lines.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: literalinclude and line wrapping in Latex

[Guenter Milde]

On 2012-02-10, Jose Gomez-Dans wrote:

> I am grabbing data from some configuration files using literalinclude.
> These files are plain ASCII and are properly processed for the HTML
> documentation. For the PDF, however, the lines are too long, and get
> clipped out. I understand that this is because sphinx is putting the
> contents into a Verbatim environment, that doesn't do line breaks.

> I can't modify the input files and split them, as they are
> configuration files. I was wondering whether there's something to let
> latex/sphinx know that I want those lines wrapped? I think the
> listings or minted packages deals with this problem, but haven't seen
> them used in conjunction with sphinx.

The Docutils latex writer has a config option to use the listings
environment for literal blocks. I don't know whether this is ported to
Sphinx, though.

Another option is to define a different "teletype" font in the LaTeX
preamble, e.g. with 

  \renewcommand{\ttdefault}{txtt}

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Numbering of code lines

[Guenter Milde]

On 2012-01-18, Nikolaj wrote:
> Hello group,

> Sorry if I bring this subject back but I couldn't find any
> satisfactory answer on the net.

> I'm using Sphinx v1.1.2 with Pygments 1.4 under Ubuntu 11.04 64 bits.

Which Docutils version (try, e.g., ``rst2html --version``)?

> I could not find how to start the numbering of code (C++) lines with
> any number.

> For example, the rst-directive "literalinclude" doesn't have (AFAIK)
> an option to specify a starting number.

> I would like to have

> 56 first line of code
> 57 second line of code

> in my documentation.

> What is the easiest/best way to do this?


With Docutils 0.9 

(currently only available as developer version from SVN__):

Are the code lines in a separate file?

  No: use the "code" directive
  http://docutils.sourceforge.net/docs/ref/rst/directives.html#code

  Yes: use the "include" directive with the :code: option
   and eventually the :start-line: and :end-line: options.
   
http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment

For line numbers, use the option

  number-lines : [start line number]
Precede every line with a line number. 
The optional argument is the number of the first line (defaut 1). 

Example::

  .. include::  myfile.cc
 :code: C++
 :start-line: 57
 :end-line:   58
 :number-lines: 56
 

   
Günter

__ 
http://docutils.sourceforge.net/docs/dev/repository.html#accessing-the-repository

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: section* vs. section commands in LaTeX writer

[Guenter Milde]

On 2012-02-06, Eric Jacoboni wrote:

> I'm wondering if it's possible to configure sphinx for producing
> unnumbered versions of sectionning commands (chapter* instead of
> chapter, section* instead of section, etc.) with the LaTeX Writer.

Docutils has the "sectnum" directive that enables section numbering - i.e.
by default sections should not be numbered. (It may be the Sphinx LaTeX
writer overrides this and defaults to sectioned numbers.)

> For now, i'm editing manually the .tex files generated... but it could
> be cumbersome on big documentations...

The "starred" section commands require special commands to be included in
the ToC and to become hypertargets.

Docutils 9 (the developer version from SVN) uses a different strategy to
suppress the numbers:

The preamble command

  \setcounter{secnumdepth}{0}

It can also be specified in the config file.

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Issue with .. note:: and similar

[Guenter Milde]

On 2011-08-29, Infinity77 wrote:

> However, now I am getting this kind of errors:

> E:\AGW\agw\aui\auibook.py:docstring of
> aui.auibook.AuiNotebook.DeletePage:6: (ERROR/3) Error in "note"
> directive:
> invalid option block.

> Which is fantastically wrong as the "note" directive is perfectly
> valid:

>:note: L{DeletePage} removes a tab from the multi-notebook, and
> destroys the window as well.

> I pre-process the docstrings using this approach:

> def setup(app):

> app.connect('autodoc-process-docstring', mangle_docstrings)


> In which I replace the L{something} with an appropriate ReST link and
> I replace the ":note:" attribute with ".. note::" (I have to do this
> because of backward compatibility with epydoc).

> Now, I am not sure what has changed in Sphinx to make this happen, but
> I welcome any suggestion in order to fix this issue (I have many more
> errors related to ".. note::", ".. warning::" and friends.

Did you update the Docutils, too?

Release 0.8 (2011-07-07) introduced:

  - Most directives now support a "name" option that attaches a
reference name.

  - Directive content may start on the first line also when the directive
type accepts options.

However, in order to distinguish between a directive block and the directive
argument, you may not start a "field list" on the first line of a directive
that accepts options::

  ..note:: :this: is a field list
   :interpreted: as option block
   
The Docutils 0.8 parser only checks for a colon starting a line, so that
the following two examples fail as well:

  .. note:: :code:`a == b` test the equality :math:`a = b`

  .. note:: a role is
 :strong:` not an option`.

Workarounds:

Write the content in the content block (separated from the directive start
by a blank line)::

  ..note:: 
  
:this: is a field list
:interpreted: as field list because it is preceded by a blank line

Use role suffix instead of prefix::

  .. note:: `a == b`:code: test the equality :math:`a = b`


Use different line breaks::

  .. note:: a role is :strong:` not an option`.





For your problem, you might try:

  replace the ":note:" attribute with ".. note::\n\n"

(there might be problems with the indentation, though).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Output-format-dependent substitution

[Guenter Milde]

On 2012-01-10, Purnank H G wrote:


> On Jan 10, 1:16 am, andreash  wrote:
>> Hi Sphinx experts,

>> how can I make a substitution depending on the output-format?

>> Basically, I would like to have something like this::

>>    if html:
>>       |CLICK| unicode:: U+21E8
>>    elif latex:
>>       |CLICK| raw:: latex

>>                  $\LongRightArrow$


> For a similar problem, I use a very ugly but simple workaround in
> http://eclipsebook.in/

> I use separate conf.py for different formats,

...

> All the conf.py have this line:

>  rst_epilog = "\n.. include:: /%s/include-post-conf.txt\n\n" %
> (os.path.abspath('.'),)

...

An implementation of this idea in reStructuredText would be a new
"format" keyword for the include directive
http://docutils.sourceforge.net/docs/ref/rst/directives.html#including-an-external-document-fragment
that acts like the format specifier in "raw" and "raw"-defived roles
http://docutils.sourceforge.net/docs/ref/rst/roles.html#raw.

Example::

  .. include:: latex-substitutions.txt
 :format: latex
  .. include:: substitutions.txt
 :format: html xml pseudoxml manpage


This could be implemented in Docutils (which means it would automatically
work in Sphinx after installing of the "augmented" Docutils version).

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Output-format-dependent substitution

[Guenter Milde]

On 2012-01-09, andreash wrote:
> Hi Sphinx experts,

> how can I make a substitution depending on the output-format?

> Basically, I would like to have something like this::

>if html:
>   |CLICK| unicode:: U+21E8
>elif latex:
>   |CLICK| raw:: latex

>  $\LongRightArrow$


Ugly workaround:

.. |CLICK| raw:: latex

$\LongRightArrow$

.. |CLACK| raw:: html

⇨

Now |CLICK|\ |CLACK| here!

Another option would be to add a conversion for U+21E8 in the
LaTeX preamble. The latex writer uses e.g.

  '\\DeclareUnicodeCharacter{00A0}{\\nobreakspace}',

* I recommend \ensuremath{\LongRightArrow} to get this working in both
  text and math.
* of course this requires that you use utf8 encoding for
  the latex source. 
* Untested!

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: equations references across files

[Guenter Milde]

On 2012-01-08, Ondřej Čertík wrote:
> On Fri, Jan 6, 2012 at 3:22 PM, Fernando Perez  wrote:
>> 2012/1/6 Ondřej Čertík :

...

>> are the other parts of writing a thesis/book with sphinx working OK
>> for you?  I'm thinking:

>> - labeled references for other elements besides equations, such as saying

>> as we discuss in sec. \ref{integral}, then...

>> in TeX, this will provide proper section number references, and can be
>> used for pages, etc. 

This is not currently implemented in Docutils/Sphinx. It would be easy to
achieve for LaTeX output, but in HTML this requires a transform that
extracts the section/table/theroem/... number and uses it as link text.

See the test 
http://docutils.sourceforge.net/sandbox/latex-variants/tests/figure-reference.txt
for an example how this works with Docutils. (Not tested with the Sphinx
LaTeX writer.)

See also the Docutils TODO list
http://docutils.sourceforge.net/docs/dev/todo.html#object-numbering-and-object-references


>> - clean use of bibtex, including style file control.

> Not implemented.

This is a long standing TODO list item.
http://docutils.sourceforge.net/docs/dev/todo.html#footnote-citation-gathering
There is some support with the external bibstuff add-on
http://code.google.com/p/bibstuff/
and with `Zotero plain`
http://e6h.org/%7Eegh/hg/zotero-plain/



>> - figure placement hints for floating figures.

> This should hopefully be possible by modifying the Tex code generation.

You can already configure the float placement with the help of the "float"
package - globally with e.g. ::

  \usepackage{float}
  \floatplacement{figure}{tb} 

in the LaTeX preamble, locally with raw latex like:: 

  .. raw:: latex

\floatplacement{figure}{tb}

See
http://docutils.sourceforge.net/docs/user/latex.html#figure-placement


...


> However, it just occured to me, that almost all of the problems could
> be fixed by simply merging all the .rst files into one by my own
> script, and only then giving it to Sphinx. 

Instead of merging the .rst files, you can simply ``.. include::`` them
into a "master" document. Then, you might also consider using Docutils
instead of Sphinx for the LaTeX generation.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Feature Request: Auto-Extracting Examples

[Guenter Milde]

On 2012-01-06, Bruce Eckel wrote:

> I'd love to see some kind of tag that indicates that something is, or is
> part of, a working example, so that Sphinx would automatically extract the
> example and it could be downloaded, run, etc.

> I ask for this because I see too much documentation where the author says
> "here's how to do it" and then gives some untested code fragment. I think
> if this (admittedly low, but apparently enough to keep people from doing
> it) hurdle were removed, we'd see far more working examples.

I don't know whether it fits into your work flow, but the PyLit converter
at http://pylit.berlios.de allows to convert a document between "text" and
"code" formats (i.e. rst document with code parts and source code with
comments). This way a complete documentation file can be used at the same
time as a running example, test case, config file, or template.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How to reduce memory usage of sphinx-build

[Guenter Milde]

On 2012-01-06, Neck Acm wrote:

> Hi all, I am new to sphinx, I am trying to convert massive plain text
> files to well-organized html, not program documentation, just some
> plain text record.

> The source text files is about 116 MB
...
> eventually eats all my memory ( 1.5 GB ), returning MemoryError, abort
> the build process

This is gigantic. How many lines are this?

> I've tried to build with less files( 9.8 M ), sucessfully create
> beautiful html,

In the docutils-users list 
http://docutils.sourceforge.net/docs/user/mailing-lists.html#docutils-users
is a recent thread with exactly this problem: even with input files of
about 4 Mb, compilation took half an hour.

Investigation showed that the Docutils parser does not scale well - Docutils
is simply not built for massive input files.

As Sphinx uses Docutils for the document conversion, the problem should be
the same here.

> Is there any way to reduce memory usage in building 

* No easy way. You might try to fix some issues in the Docutils
  parser/writer but the developers currently have no ressources to deal with
  this.

* The recommended way is to split the document into separate documents.
  Sphinx provides good support for inter-document links.

> and the file size of output html ?

* does the html size scale linear with the input file size?

* you might consider converting to e.g. epub, which is basically zipped HTML.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Underfull \hbox (badness 10000) in paragraph at lines... in Sphinx 1.1.2

[Guenter Milde]

On 2012-01-02, Kristina D.C. Hoeppner wrote:

> Thank you very much for your explanation. It is interesting though
> that one of the underfull warnings is only given for "warning" but not
> "note". However, as it is just a warning, I'll review them and see if
> I can ignore them.

The "underful \hbox warning means that a line is too short
(i.e. not reaching the right margin). This means it very much depends on the
content of the admonition (warning, note, ...) whether this warning occurs.

I suppose you will see this warning with a note too, if you change the notes
content - just play with it (most simply by changing the generated LaTeX
source and re-running latex...).

Of course, a clean solution would be to avoid needless warnings (as they
tend to mask the places where the warnings are sensible). Maybe the
Sphinx-generated LaTeX source is not "clean" and could be improved.

BTW: overfull \hbox warnings might be far more serious: they signify a line
that goes into the margin. Sometimes this is not visible (1 pt or so) but
sometimes (especially with teletype/monospace/literal text) it requires
action.


Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Underfull \hbox (badness 10000) in paragraph at lines... in Sphinx 1.1.2

[Guenter Milde]

On 2012-01-01, Kristina Hoeppner wrote:

> I get a number of "Underfull \hbox (badness 1) in paragraph at
> lines..." warning when I generate a LaTeX PDF in Sphinx 1.1.2.

This is just a warning. Have a look at the PDF output on the relevant
line(s) and see if you can just ignore it.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: different rendering of images size and position of sphinx html to latex to pdf

[Guenter Milde]

On 2011-12-13, maning sambale wrote:
> Thanks Günter for the advice.

> I was able to control image size by specifying the "real" units.  

Fine. BTW: it should suffice to specify just one of height or width.

> The "image on the last page of the preceding project page" problem
> still persist.  The images I am pertaining to are the project logos
> which should be on the first page of the project page.

I can't tell you the reason for this without seeing the LaTeX source, as
this may depend on document class, \maketitle, stylesheets, packages, ...
as well as the image loading command and its context.

You could try to hand-edit the LaTeX source until you get the desired output
and post a diff - them we could try to reverse engineer the required changes
to the rst source or the config file.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: different rendering of images size and position of sphinx html to latex to pdf

[Guenter Milde]

On 2011-12-09, maning sambale wrote:

> I am trying to compile a pdf version for printing of the OSGeo Live
> DVD documentation [0] the sources are available in the svn [1].

> I did the following:

> 1. Modified the conf.py for latex generation.
> 2. Created a separate index.rst as the source of the toctree since the
> default index.rst doesn't have a logical ordering of rst files.
> 3. Run make latex and pdflatext textfile.tex

> So far, I get good results, however some issues are:

> 1.  Running pdflatex, I get lots of errors for gif and png images like this:
>  LaTeX Error: Unknown graphics extension: .gif.
...

GIF images are not supported by LaTeX. You need to convert them to PNG and
reference the png version in the source.


> 2. Images doesn't align similar to the html output. See this html [2]
> and this pdf image [3]

Neither alignment nor size is guaranteed to be equal in different output
media in all cases.

> 3.  The project and osgeo logo are large and always on the last page of the
> preceding project page.  Unlike in the html where it is on the
> upper-right corner.  See this [4] and this [5]

To guarantee equal size, the size must be specified in "real" units (cm, pt,
inch) not in relative units (em, px). If there is no size specified for a
bitmap image, the size in the end document depends on the resolution (px per
inch) wich is configurable (while setting a fixed size in the source is
easier).


> What I want is to modify the rst files (and avoid tex munging if
> possible) so that I can push my changes to svn.

Try whether PNG images and specifying the size in the source already solve
your problems.

BTW: For scalable (vector) images, you need separate formats for HTML
(SVG) and LaTeX (PDF).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Is there possible for bold and italic text

[Guenter Milde]

On 2011-12-12, lyhcode wrote:
> rst has
> *italic*
> **bold**

> but if I need a text bold and italic in the same time.
> something like

> ***italic.bold***

> Is there a easy way to implement this?
> thanks a lot

Currently, nested inline markup is not supported. The workaround is easy but
not nice:

define a custom role, e.g.

.. role:: bfit

and use it to mark up :bfit`bold italic text`.

You also need to define styling rules for the bfit class in the CSS
stylesheet for HTML and in the LaTeX preamble for LaTeX.

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: How to include an additional pure Docutils directive as extension?

[Guenter Milde]

On 2011-12-08, Martin Bless wrote:

> Q: How can I add a pure Docutils directive - that does not inherit
> from sphinx.util.compat.Directive - to Sphinx? Is that possible?

As the Sphinx config file is Python code, you could try to replicate the
steps otherwise done in a Docutils front-end, i.e. register the directive
with Docutils. I.e. in config.py::

  from docutils.parsers.rst import directives
  from wherever.you.store.it import your_directive

  directives.register_directive('code-block', your_directive)


untested.

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Sphinx vs. docutils for textbook

[Guenter Milde]

On 2011-12-01, Bob Plantz wrote:
> I am converting a textbook I have written in LaTeX to epub. The book
> (500+ pages) is on assembly language. It has many drawings (vector
> graphics), a fair amount of math equations (but only simple algebra
> notation), and many code listings. My goal is to make it available
> both in epub (for ereaders) and pdf (for printing).

> So far I have been converting the source to rst and using docutils for
> producing the two versions of the book. I have learned how to include
> different versions of the figures in the final product: svg for epub;
> eps for pdf (via LaTeX). Common html seems to be adequate for my
> equations, and the code listings look good (although I would like to
> be able to add line numbering).

> Does Sphinx offer advantages for such a project over "raw" docutils?

* Document splitting and cross-referencing.
* Special roles and directives for code documentation
  (may be not required by your project)
* ready-made epub extension.

IMV, Sphinx is the better choice for large projects (web sites ...) while
Docutils is for "stand-alone" documents.

BTW: In the development version, Docutils now also supports syntax
highlight with a "code" directive and role. Since version 0.8, math is
supported.

> Keep in mind that I'm an assembly language programmer. In other words,
> sort of a control freak. I don't like programs that have a mind of
> their own, for example, MS Word.

Both, Sphinx and Docutils offer comprehensive configuration options and can
also be used programatically.

> Yes, this is lots of work. But I'm retired, and the problem of
> publishing technical books in epub interests me. Good way to keep my
> mind active.

We had some discussion about the missing parts for scientific writing
with reStructuredText here as well as on the docutils list
(citation/reference support, epub intergration, footnotes, ...).
There is plenty of work and of food for thought :-)

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Splitting HTML output at subsection boundaries

[Guenter Milde]

On 2011-12-06, Fernando Perez wrote:
> On Thu, Dec 1, 2011 at 9:04 AM, Friedrich Romstedt
> wrote:
>> 2011/12/1 Fernando Perez :
>>> On Thu, Dec 1, 2011 at 2:56 AM, Friedrich Romstedt
>>>  wrote:


> Many thanks for the informative posts and discussion.  It does seem
> that sphinx is actually getting closer and closer to what at least we
> in ipython will need for solid rest-based latex export of
> computational sessions.

For converting a single session into a single document, I would recommend
Docutils over Sphinx.  The additional layer introduced by Sphinx is
mainly to accomodate larger projects consisting of a set of documents.

> For those who may be curious, there are already users 'publishing' from
> ipython notebooks, in the form of blog posts:

> http://lighthouseinthesky.blogspot.com/2011/10/curve-fitting-part-5-pymc.html

> Unfortunately right now that requires manual cleanup of the html/CSS,


> so we'd like to make it more user-friendly.  But the real goal in the
> long term is to at least narrow the gap between the environment you
> work in to obtain your results, and what you write up as a final
> paper.  There is enough touchup involved in a paper that the final
> form will probably always be something edited in TeX/LyX/etc, but
> hopefully that will be a document that can be started from a closely
> related, and otherwise scientifically equivalent, executable session.
> Then you could supply, as part of your supplementary materials, this
> notebook.  There are obviously issues with how to expose your data,
> etc, that are non-trivial and the subject of much current discussion
> at journal editorial boards, funding agencies and research centers,
> but at least I think this can be a contribution in the right
> direction.

Advertisement: For the related topic of a non-interactive scripts:
I recommend a look at

  PyLit (Python Literate) provides a plain but efficient tool for
  literate programming: a bidirectional text/code converter.

  -- http://pylit.berlios.de/

With this, a program source can be easily converted between “text” and
“code” formats

The “code” source can be debugged, compiled or executed with standard
tools.

The “text” source can be converted to HTML or LaTeX documents, e.g. with
the Docutils or Sphinx.

Both formats hold the full information. Round-trips are possible without
loss, hence it is easy to keep them up-to-date during development.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] MathML (was Re: Splitting HTML output at subsection boundaries)

[Guenter Milde]

On 2011-12-03, Friedrich Romstedt wrote:
> Hello Guenter,

>>> 3)  Maths as PNGs (if not using JSMath, what is not an option for
>>> ebook readers) not properly aligned in inline text mostly.

>> Since version 0.8, Docutils supports math with MathML and HTML+CSS output
>> options in HTML. (I don't know how good these work in ePub, though.)

> OK, this is pretty cool.  Unfortunately the Wiki on mathweb.org
> referenced from
> http://docutils.sourceforge.net/docs/user/config.html#math-output
> seems nonfunctional (it tries to download the php script for me).

Fixed. Thanks for reporting.

> How would one enable MathML with Sphinx?

Use Docutils >= 0.8, the :math: directive but not the Sphinx math
extension. Watch for the differences and limitations
>> http://docutils.sourceforge.net/docs/ref/rst/directives.html#math

How to select MathML output for html, I don't know, but there should be
some way to pass configuration settings to Docutils.

> Still, I would rather stick to PNGs which are aligned properly
> (plastex?), for portability.  But it sounds good.

PNGs have the big disadvantage that you cannot copy/search/select the
content. Also, they do not scale (which is especially bad in an e-book).

Some e-book readers support SVG, so this may be an option. However,
converting LaTeX math output to SVG does not work well because the math
fonts have special, non-standard alignments. It will only work
satisfactorily with XeTeX or LuaTeX, the unicode-math package and
OpenType fonts.

However, the --math-output=HTML option should be scalable, searchable, and
portable - as long as the target device supports CSS2.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Splitting HTML output at subsection boundaries

[Guenter Milde]

On 2011-12-01, Friedrich Romstedt wrote:
> 2011/11/30 Olivier Bonaventure :


> I tried once to write my Dipoma thesis in Sphinx, because I thought
> the same as you do.  But I switched back to LaTeX later, rewriting all
> the stuff again.  The reasons are that Sphinx/Docutils is nice for
> HTML documentations of Programs, but the functionality just lacks some
> ingredients of LaTeX I really like and miss then:

What I miss most, is citation management with a database like bibtex.

> 1)  Spanning paragraphs over equations.  Paragraphs are in Docutils a
> nonstructured entity.  In depends on the point of view if this is a
> design mistake or not.  For the Sphinx purpose, it might be not, for
> the (e)paper document it probably is.  I do not think we would like to
> discuss this here again, just to point it out.

There is the "compound" directive in reStructuredText:
  
  The "compound" directive is used to create a compound paragraph, which
  is a single logical paragraph containing multiple physical body
  elements such as simple paragraphs, literal blocks, tables, lists,
  etc., instead of directly containing text and inline elements. For
  example::

  .. compound::
  
 The 'rm' command is very dangerous.  If you are logged
 in as root and enter ::
  
 cd /
 rm -rf *
  
 you will erase the entire contents of your file system.

   -- http://docutils.sf.net/docs/ref/rst/directives.html#compound-paragraph


> 3)  Maths as PNGs (if not using JSMath, what is not an option for
> ebook readers) not properly aligned in inline text mostly.

Since version 0.8, Docutils supports math with MathML and HTML+CSS output
options in HTML. (I don't know how good these work in ePub, though.)
http://docutils.sourceforge.net/docs/ref/rst/directives.html#math

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Some characters rendering wrongly in HTML output

[Guenter Milde]

On 2011-11-25, Guenter Milde wrote:
> On 2011-11-25, Friedrich Romstedt wrote:
>> Am 25.11.2011 um 08:44 schrieb Guenter Milde :
>>> On 2011-11-24, Friedrich Romstedt wrote:

>>>> I'm experiencing some problem with Sphinx 1.1.2 (and also an earlier
>>>> version from July), that some characters in my HTML  are
>>>> occuring as strange Unicode character sequences in the HTML.  Here's
>>>> an example:

>>>> http://www.roentgen.physik.uni-goettingen.de/~fromstedt/

>>>> Watch the title displayed in the browser (not the headline, but the
>>>> title).  The two-character sequence is hardcoded like this in the
>>>> HTML, apparently (inspection with Firefox "Show Source").

> I cannot tell the reason.

Found out more:

* if I download the page and open the copy from file, title and "section
  tags" are OK.
  
* if i manually set the encoding (in my Firefox it is Ansicht>Zeichenkodierung
  and I click at the already selected utf-8), the problem vanishes as well.
  
  (The "Seiteninformationen" show ``Coding: ISO-8859-1`` before and
  ``Coding: UTF-8`` after this change.)
 
Guess: 
  The http server sends some header that makes the browser reading the
  document as ISO-8859-1 (latin1) encoded.
  
Solutions:
  * configure the server to announce utf-8 if the doc is utf-8 encoded, or
  * configure Sphinx to write "ascii" or "latin1" encoded documents
(in Docutils the setting is "output-encoding", should be something 
similar in Sphinx)

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Some characters rendering wrongly in HTML output

[Guenter Milde]

On 2011-11-25, Friedrich Romstedt wrote:
> Am 25.11.2011 um 08:44 schrieb Guenter Milde :
>> On 2011-11-24, Friedrich Romstedt wrote:

>>> I'm experiencing some problem with Sphinx 1.1.2 (and also an earlier
>>> version from July), that some characters in my HTML  are
>>> occuring as strange Unicode character sequences in the HTML.  Here's
>>> an example:

>>> http://www.roentgen.physik.uni-goettingen.de/~fromstedt/

>>> Watch the title displayed in the browser (not the headline, but the
>>> title).  The two-character sequence is hardcoded like this in the
>>> HTML, apparently (inspection with Firefox "Show Source").

>> Show source reveals:

>> Welcome to Friedrich Romstedt’s IRP Home! — I
>>RP - Friedrich Romstedt


Interestingly, the section title in the document body reads

   Welcome to Friedrich Romstedt’s IRP Home!...
   
with a numerical replacement for the RIGHT SINGLE QUOTATION MARK.

...

>> There is a similar problem with the "pop-up
>> anchors" of the section headings. If I move the mouse over a section
>> heading, I see something like:

>> Welcome to Friedrich Romstedt’s IRP Home!¶

and the HTML source shows this also in other section titles:

  Overview¶
  


>>> In that example, the two-char sequence results from an apostroph ' .

>> Sphinx uses "smartypants" to convert

>> Character ' (39, 0x27) APOSTROPHE
>> to
>> Character '’' (8217, 0x2019) RIGHT SINGLE QUOTATION MARK

>> Maybe you can disable this replacement.

> If I know how; although I would prefer a real fix / explanation. 

I don't know either. Should be somewhere in the Sphinx docs or in the
config file template.

...

>>> If anyone has an idea how to track this down, it's very much welcome.

>> In "Romstedt’s", the three bytes of the UTF-8 representation of the 
>> Character '’' (8217, 0x2019) RIGHT SINGLE QUOTATION MARK
>> are treated as three characters.

> Three bytes?  Meaning ' is an digraph even though it is Unicoded?  I
> remember there are several possibilities to encode some characters in
> Unicode. 

It's not a digraph, but the UTF8-encoding of Unicode represents
every character outside the ASCII range as a sequence of up to four bytes.

``¶`` are the two bytes representing 00B6 PILCROW SIGN in UTF-8 encoding.

>> How do you specify the title?

> Currently by the headline. I will try the .. title:: next.

By headline, you mean a section title in the rst source like::

   Welcome to Friedrich Romstedt's IRP Home!
   -

? (I try to exclude encoding problems in the configuration file or style
sheets.)

>> What is the locale encoding?

... 

from your other post I see that it is UTF-8 (should be fine).

What are the settings for input encoding and output encoding in the Sphinx
config file?

Something strange is going on here:

* the html source defines itself as utf-8::



* Unicode chars in the text are replaced with "numbered entities"
  (like ’)
  
* Unicode chars in "special places" (moved to the title, auto-added section
  marks) are "doube-encoded" in utf-8.  

I cannot tell the reason.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Some characters rendering wrongly in HTML output

[Guenter Milde]

On 2011-11-24, Friedrich Romstedt wrote:
> Hi,

> I'm experiencing some problem with Sphinx 1.1.2 (and also an earlier
> version from July), that some characters in my HTML  are
> occuring as strange Unicode character sequences in the HTML.  Here's
> an example:

> http://www.roentgen.physik.uni-goettingen.de/~fromstedt/

> Watch the title displayed in the browser (not the headline, but the
> title).  The two-character sequence is hardcoded like this in the
> HTML, apparently (inspection with Firefox "Show Source").

Show source reveals:

 Welcome to Friedrich Romstedt’s IRP Home! — I
RP - Friedrich Romstedt

Is this the same as in your *.html source (if you look at it in a text
editor) or is there some additional change introduced on its way over the web?

Looks like an encoding problem. 

> I have no idea how to boil this down since it's just the  which
> is affected. 

There is a similar problem with the "pop-up
anchors" of the section headings. If I move the mouse over a section
heading, I see something like:

Welcome to Friedrich Romstedt’s IRP Home!¶

> In that example, the two-char sequence results from an apostroph ' .

AFAIK, Sphinx uses "smartypants" to convert

Character ' (39, 0x27) APOSTROPHE
* neutral (vertical) glyph with mixed usage 

to  

Character '’' (8217, 0x2019)
2019RIGHT SINGLE QUOTATION MARK
= single comma quotation mark
* this is the preferred character to use for apostrophe

At least this is what I see in the first section heading.

Maybe you can disable this replacement.

> I think that my vim on my institute computer writes out just plain
> ASCII (i.e., not 16bit Unicode).  ``file`` says::

> ASCII English text

If it really writes just ASCII, how do you write Röntgen in your source
files?

> If anyone has an idea how to track this down, it's very much welcome.

In "Romstedt’s", the three bytes of the UTF-8 representation of the 
Character '’' (8217, 0x2019) RIGHT SINGLE QUOTATION MARK
are treated as three characters.

How do you specify the title?

What is the locale encoding?

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: conditional exclusion of rst files

[Guenter Milde]

On 2011-11-23, Viktor Haag wrote:
> On Wednesday, 20 July 2011 06:39:43 UTC-4, Alastair Dent wrote:

>>  I need to be able to exclude specific rst files, depending on a built 
>> parameter.

You might try with a "condotional include" directive like

.. only:: ...
   .. include:: foo.txt

> The right answer might very well be much more simply done with N different 
> conf files, N different "contents" files, and a cunningly structured source 
> tree to minimize duplication of source outside the conf and contents 
> files... 8(

Maybe a version control system with good support for branches (git, ...)?

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Drawing trees

[Guenter Milde]

On 2011-11-17, Felix Hummel wrote:
> Hi Carlos,

> as far as I know, there is no reSt directive offering a nice tree
> representation in both HTML and PDF.

...

> Of course you could go fancy with Graphviz ...

There is a graphviz extension for Sphinx.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: chapter numbering

[Guenter Milde]

On 2011-11-11, Daniele Zambelli wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Hi,

> I wish that the chapter numbering starts at 0 instead of 1.

> It is possible do this?

Yes. 

Use the :start: option to the sectnum directive. See
http://docutils.sourceforge.net/docs/ref/rst/directives.html#automatic-section-numbering

Günter


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: multiple replace

[Guenter Milde]

On 2011-11-07, Alex Wilkie wrote:

...

> I am putting lots of repeated rst in files that I am "including" in
> the actual source rst for a given file that I am documenting. As these
> files that need to be documented there is a lot of duplicated class
> attributes that have different prefixes - an example is probably
> clearer!

> [generic.rst]
>   .. attribute: |prefix|_my_attr
>  this is the |prefix|_my_attr dox

> [file1.rst]

> .. |prefix| replace:: foo

> .. include:: generic.rst

> .. |prefix| replace:: bar

> .. include:: generic.rst

> I'm hoping this would result in nice formatted replaced text in the
> result of file1 something like:

>   .. attribute: foo_my_attr
>  this is the foo_my_attr dox

>   .. attribute: bar_my_attr
>  this is the bar_my_attr dox

> But instead I get multi replace definition errors...

This is Docutils (current) behaviour, it ensures you do not accidentially
overwrite a substitution reference in one document.

The "include" directive "embeds" the included file before parsing, so it is
equivalent to placing the file content inline.

It should, however, be possible to have *separate* documents, all including
generic.rst and setting different replacements.

I don't know if this also works for separate documents that are interlinked
via the Sphinx toc. (I guess it works with HTML and fails with LaTeX.)

> Does this make anysense to anyone? Is it currently possible? How would
> I go about writing a custom directive to achieve it?

Writing a custom directive would be quite "invasive": it would require
changes in the way substitutions are done. The Docutils developer
documentation and the Docutils source will give hints.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Exception running Sphinx

[Guenter Milde]

On 2011-11-06, Greg D wrote:
> Hi,

> I'm attempting to install tortoisehg-py27 on my Mac, using fink.  When
> I do, I get the following report.  Any suggestions re: what went
> wrong, and how to get it working, would be greatly appreciated.

...
> python2.7 ../sphinx-build.py -b latex -d _build/doctrees. _build/
> latex

> Exception occurred:
>   File "/sw/src/fink.build/sphinx-py27-1.0.5-1/Sphinx-1.0.5/sphinx/
> writers/latex.py", line 105, in ExtBabel
> _ISO639_TO_BABEL = Babel._ISO639_TO_BABEL.copy()
> AttributeError: type object 'Babel' has no attribute
> '_ISO639_TO_BABEL'

...

This is caused by an incompatibility between Sphinx and Docutils version
0.8. 

It is fixed in Docutils version 0.8.1 which should work with Sphix 1.0.8.
If possible, update both Docutils and Sphinx.
Downgrading the Docutils installation should solve the problem, too.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Non-compact lists do not wrap sub-lists in paragraph

[Guenter Milde]

On 2011-11-04, Friedrich Romstedt wrote:
> 2011/11/4 Guenter Milde :
>>> It appears by inspection of the html source code, that indeed the
>>> sublist is not contained in a  tag.  This appears like a mistake to
>>> me.  Because it should be a paragraph, since it is an entity on its
>>> own to be rendered such.  It also generates a rather wrong-looking
>>> visual impression of the rendered html output.

>> I don't think that a sub-list of a list should be nested in a paragraph
>> element.

> OK, I don't think I'm knowledgable enough to decide that.  But to a
> LaTeX user, a list makes a paragraph, although it might contain
> paragraphs in its items.

In Docutils, lists are "paragraph like block level objects" and the
content of a list item is always put in a paragraph (as the pseudoxml
output of the example shows):


This not:



item 1



subitem 1.1


subitem 1.2


item 2

second paragraph

The relationship between the objects is defined in
http://docutils.sourceforge.net/docs/ref/doctree.html#element-hierarchy
The standard HTML writer omits the paragraph tags around list item content.
(The html-strict writer is more consistent here and adjusts the CSS style
sheet to get the compact/non-compact distinction.)

In LaTeX, text is not structured by putting it in a "paragraph object"

   first paragraph 
   second paragraph 

(the \paragraph macro is actually a section heading).
Rather a "paragraph separator" is used:

  first paragraph
  
  second paragraph

Hence, the question whether a list is an "instance" of a paragraph or should
be embedded into one does not apply.


BTW, in LaTeX, you can write both, lists that are separate from the
context and lists that are "embedded" - depending on whether the \begin
\end pair is offset from the pre/post text with blank lines.

In rst, embedded lists are not possible, the syntax requires blank lines
around a list. (To embed a list in a paragraph, you need a "compound"
directive.)

...

>>> I would appreciate a solution, since I'm
>>> observing this mistake since years now; although I seem to be a rare
>>> case in constructing such lists, it apprears regularly to me.

>> I suppose that the visual impression of the rendered html output is due
>> the used CSS style sheet and can be fixed in a style sheet (either as a fix
>> in the default Sphinx style or as a workaround in a custom style sheet).

> I also agree that it seems to be style sheet related.  I think it can
> be solved fully via this.  I see that the ``simple`` as well as the
> ``first`` classes are missing at least in the default + nature style
> sheets; it is the ``ol.simple, ul.simple`` that introduces
> ``margin-bottom:1em``.

> Now that I know what I have to work on I can try a fix.

Attention: AFAIK the "! important" feature is not supported by ePub. It
might be better to list the relevant objects in the specifier (divided by
``,``), e.g. ::

.first {
  margin-top: 0 }

.last, ol.simple.last, ul.simple.last, .with-subtitle {
  margin-bottom: 0 }


> P.S.: I was apparently too quick in believing that the  tag is
> necessarily the only solution.  Although I still believe it is a more
> elegant solution.  The browser can decide how much space to place, and
> the stylesheet does not need to say ``1em`` explicitly.  I have put my
> thoughts in a comprehensive form on
> http://friedrichromstedt.github.com/lists1.html, with an example how
> it could work out in terms of resulting HTML.

IMV, not a good idea: what happens, if you decide to separate
paragraphs by indentation like

p {
   margin-bottom: 0
}
p + p {
   text-indent:1.5em;
   margin-top:0
}

?

Besides this, the change to add the  tag would be required in the
Docutils html writer that does not exhibit the problem.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Non-compact lists do not wrap sub-lists in paragraph

[Guenter Milde]

On 2011-11-03, Friedrich Romstedt wrote:

> It seems there is a kind-of problem with sub-lists in non-compact lists.

...

> *   item 1

> -   subitem 1.1
> -   subitem 1.2

> *   item 2

> second paragraph

...

is rendered like:

> *   item 1

> -   subitem 1.1
> -   subitem 1.2
> *   item 2

> second paragraph

...

> -  The second list should contain spaces between all paragraphs, but
> the space between the sublist and the following item of the top-level
> list is missing.

...

> It appears by inspection of the html source code, that indeed the
> sublist is not contained in a  tag.  This appears like a mistake to
> me.  Because it should be a paragraph, since it is an entity on its
> own to be rendered such.  It also generates a rather wrong-looking
> visual impression of the rendered html output.

I don't think that a sub-list of a list should be nested in a paragraph
element.

> I don't know it this issue is a general docutils issue or if it can be
> handled within Sphinx. 

I compiled the example with Docutils (rst2html.py). In my browser
(firefox as well as midori) there is the correct "paragraph separating
space" between "subitem 1.2" and "item 2" (with the default stylesheet
html4css1.css).

> I would appreciate a solution, since I'm
> observing this mistake since years now; although I seem to be a rare
> case in constructing such lists, it apprears regularly to me.

I suppose that the visual impression of the rendered html output is due
the used CSS style sheet and can be fixed in a style sheet (either as a fix
in the default Sphinx style or as a workaround in a custom style sheet).

Günter




-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Python 3 style Print Giving Errors

[Guenter Milde]

On 2011-11-02, James Maxwell wrote:

> [-- Type: text/plain, Encoding:  --]

> When I "make html" in Sphinx I'm getting syntax errors for Python 3 style 
> print statements such as:

> print(x,y,z,sep="\t",end="\n",file=data)
>^
> SyntaxError: invalid syntax

> The code runs fine.  I must be missing something.  I installed Sphinx 
> version 1.1.2, but still no go.
> Thanks for any help you can give,

Could it be that you run a Sphinx set up with Python 3 under a Python 2
interpreter?

What version does a simple `python` command use?

What is the python command used in the makefile?

Did you do a parallel install under python 2 and 3?

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: wrap text around figures

[Guenter Milde]

On 2011-10-31, Pietro wrote:

> I would like to wrap text around figures when figures are positioned
> on the right (or left) hand side of the page (see the
> wouldlike-pdf.jpeg). The HTML output is ok (get-html.jpeg), instead
> the LaTex generate from sphinx code reach a different result
> (get-pdf.jpeg).

> Below you can find the ReST code, the Latex that has been generated
> from sphinx and the modified version to be coherent with the HTML
> output.

> How should I modify the reST file to generate the "right" latex code
> from sphinx?

Unfortunately, the only way (except patching the latex writer) is to use
raw latex: mark the figure directive as "html-only" and put the LaTeX
code in a "raw latex" block. Don't forget to add ``\usepackage{wrapfig}``
in the LaTeX preamble.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: parsed-literal problems

[Guenter Milde]

On 2011-11-01, Georg Brandl wrote:
> On 10/29/2011 01:19 PM, Guenter Milde wrote:

...

>> I am not sure "parsed-literal" content should be highlit as code.
>> (But, of course a consistent behaviour is to be expected - i.e. either
>> always or never highlight parsed-literal as code.)
...
> you are of course right.  If I had my way, I wouldn't highlight
> anything in parsed-literal blocks.  But the problem is that I found no
> way to distinguish between normal literal blocks and parsed literal
> blocks that have only "plain" (i.e. nothing that was parsed) text
> inside...

I remember the same problem when introducing code-highlighting via the
"listings" package in the Docutils latex writer. The answer I got back then
was: "There is no need for this distinction in the standard
Docutils."

I see two ways out here:

a) Convince David that it makes sense to keep a tag of the "origin" of a
   literal_block doctree node. This could be either a class argument, or a
   "hidden attribute" as part of the "lossless rst parser" (pre-requisite to
   write back parsed documents as rst without loss of information).
   
b) Accept, sanitize and document the behaviour of "parsed-literal" in Sphinx.
   Acutally, the documentation of the directive,
   
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block
   says:
   
 Parsed literal blocks are useful for adding hyperlinks to code examples.
 
   Things to consider/document:

   * parsing order: [rst, code-highlight]  vs.  [code-highlight, rst]
   * How to represent and lay out e.g. a link that is a keyword, part of
 a string or comment?
   * Precedence for other inline markup vs. syntax highlight.

For Docutils, I rather plan to go way a). The idea is to have a configurable
"default-literal-block" directive (similar to "default-role") that maps the
"::" syntax to, e.g., "literal", "parsed-literal", or "code".

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: parsed-literal problems

[Guenter Milde]

On 2011-10-29, Andrea Crotti wrote:
> On 10/28/2011 10:28 PM, Guenter Milde wrote:
>> What do you expect and what do you get?


> I would think to get the code highlighted, instead is just not 
> recognized as code,

I am not sure "parsed-literal" content should be highlit as code. (But, of
course a consistent behaviour is to be expected - i.e. either always or
never highlight parsed-literal as code.)

> and that also if I use highlight or code-block...

The "highlight" directive is *not* intended to highlight content, instead:


  The highlighting language can be changed using the highlight directive,
  used as follows::

.. highlight:: c

  This language is used until the next highlight directive is encountered.

  -- http://sphinx.pocoo.org/markup/code.html
  

Highlighting is expected only with a standard (non-parsed) literal block
or a code-block directive::

   # this should be considered Python code (in Sphinx) unless the 
   # "highlight language" is changed.
   
.. code-block:: C

   /* this directive content should be C code */


> I filled a bug for it:
> https://bitbucket.org/birkenfeld/sphinx/issue/806/highlight-parsed-literal-not-working-for

I leave this to the Sphinx developers...

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: parsed-literal problems

[Guenter Milde]

On 2011-10-28, Andrea Crotti wrote:
> On 10/27/2011 01:54 PM, Andrea Crotti wrote:

>> It was quite simple, this is a simple failing example:
>> .. parsed-literal::
>> class SampleCommand(AbstractCommand):
>>  def do(self):
>>  # var


>> (and I don't get any compilation warnings).

What do you expect and what do you get?

> So should I file a bug report about this or it's supposed to work in 
> this way?

I think so, but cannot tell without a clear statement of the expected and
actual output.

Mind, that "parsed-literal" does not imply syntax highlight, but instead
accepts reStructuredText elements like links and inline markup.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: inline code highlighting?

[Guenter Milde]

On 2011-10-27, Tim Arnold wrote:

> [-- Type: text/plain, Encoding:  --]

> Hi, I'm learning sphinx now--great stuff!

> I'm using the code-block highlighting a lot--flipping between 'html', 
> 'latex', and 'python' languages.  For example,

> .. code-block:: latex


> Is there any directive for highlighting *inline *code? For now I'm just 
> using markup like 
> ``\section{my section title}`` when writing a bit of code for LaTeX users 
> for example.

> I'm guessing it's not possible, given my search results so far.

There is now a :code:`role` in the reStructuredText reference
implementation Docutils (http://docutils/sf.net):

Changes Since 0.8.1
===

* General:

  - reStructuredText "code" role and directive with syntax highlighting
by Pygments_.
  - "code" option of the "include" directive.

As Sphinx builds on the Docutils, upgrading Docutils to the development
version might help:

However, handling of syntax highlight in Sphinx and Docutils differs, so
your mileage might vary. Read the Docutils documentation (the one that
comes with the SVN repo or daily snapshot) in any case.



-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: parsed-literal problems

[Guenter Milde]

On 2011-10-25, Andrea Crotti wrote:
> I'm fighting a little bit in trying to understand parsed-literal.

...

> This block of code for example is recognised and colored perfectly:

...


> I thought it was just an highlighting problem, but it's just not seen
> as a parsed-literal.

What does the output look like? Is there an error message?

Does a blank line between the directive start line and the content block help?

Try to create a minimal working example: copy the "failing" block to a new
document. Remove stepwise content and try which line/part changes the
behaviour.

> What can I be missing?

Parsed literal is parsed as *reStructuredTeXt*. See
http://docutils.sourceforge.net/docs/ref/rst/directives.html#parsed-literal-block

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: LaTeX fancy formatting for admonitions

[Guenter Milde]

On 2011-10-13, Robin wrote:

> [-- Type: text/plain, Encoding:  --]

> Hello guys,

> I've been struggling for a week on a custom LaTeX style-sheet for some
> corporate documentation. Right now I managed to get it almost right.

> The only thing I miss is the formatting of the admonitions *with colors* (as
> in the default HTML theme).

> Do you know a way to colorize the background and border of those text
> blocks?

You can re-define the "notice" environment in the latex preamble. The
"grfguide" has details on color in LaTeX (look for grfguide.pdf or (with
texlive) issue `texdoc grfguide` on the command line).

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Estonian translation

[Guenter Milde]

Dear Aivar,

On 2011-09-18, Aivar wrote:

> I translated UI strings to Estonian (locale code 'et').
> http://www.aivarannamaa.ee/sphinx/sphinx.po

Thanks for sharing.

For parsing the reStructuredText sources, Sphinx uses Docutils_. For
localized directive and role names, the corresponding translations must
be added to Docutils.  This allows, e.g. in a Finnish document to write
the "include" directive as::

  .. sisällytä:: something.txt
  
and the abstract as::

  :Tiivistelmä:  This is the abstract.
  
Contributions are welcome, details are given in
http://docutils.sourceforge.net/docs/howto/i18n.html (update: specifying
and using utf-8 encoding is recommended for non-Latin scripts).
  

Günter

.. _Docutils: http://docutils.sf.net



-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: I have created locale for Serbian language

[Guenter Milde]

Dear Vitalije,

On 2011-06-02, vitalije wrote:
> Hello,
> this is my first post to this group, so I want to thank to all
> developers of such a wonderful tool.
> And now, I wish to give my two cents. Translation for Serbian language
> I have made for using in documenting my own projects. I have uploaded
> it on my server so that anyone interested in Serbian translation can
> download and unpack it in sphinx/locale folder.
> the translation is here:   http://skola.manastirgradac.edu.rs/sr.tar.gz

Thanks for sharing. (Unfortunately, the above link does not seem to work any
longer.)

For parsing the reStructuredText sources, Sphinx uses Docutils_. For
localized directive and role names, the corresponding translations must
be added to Docutils.  This allows, e.g. in a Russian document to write
the include directive as::

  .. включать:: something.txt
  
Contributions are welcome, details are given in
http://docutils.sourceforge.net/docs/howto/i18n.html (update: specifying
and using utf-8 encoding is recommended for non-Latin scripts).
  

Günter

.. _Docutils: http://docutils.sf.net

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Nepali Translation of Sphinx

[Guenter Milde]

On 2011-06-01, Matthew Gallagher wrote:
> Hello,
> We are in the process of creating a Nepali translation of the
> documentation for Schooltool(schooltool.org), which
> is built using Sphinx. As part of that process, we had to create a
> Nepali translation locale for Sphinx, and translate the strings we
> needed. We  now would like to contribute back to the community by
> adding this  language to trunk. My question is, do you have an
> official policy on which strings are to be translated/transliterated?
> Currently we have a  .po file which fits our needs,  but would be
> happy to translate more to get it fully integrated.

For parsing the reStructuredText sources, Sphinx uses Docutils_. If you
want localized directive and role names, the corresponding translations
must be added to Docutils. Patches are welcome, details are given in
http://docutils.sourceforge.net/docs/howto/i18n.html (update: specifying
and using utf-8 encoding is no longer discouraged).

Thanks,

Günter

.. _Docutils: http://docutils.sf.net

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Crash reports caused by non-ascii characters

[Guenter Milde]

On 2011-09-18, Aivar wrote:
> I discovered now that I get those crashes only when I execute "sphinx-
> build" with option "-W". Without this the error message is displayed
> fine.

> And Günter, thanks for the tip about workaround!

I think it is still worth a proper fix.
Could you please add a bug report to the tracker
http://www.bitbucket.org/birkenfeld/sphinx/issues/

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Crash reports caused by non-ascii characters

[Guenter Milde]

On 2011-08-31, Aivar wrote:
> Hi!

> In some cases, when I make syntax mistake in reST source and when
> there is a non-ascii character around, I get stacktrace instead of
> helpful message telling me where is the mistake. It's quite hard to
> track down such mistakes.

> One example is when I forget empty line after directive, for example:

> .. sourcecode:: python
> for i in range(a,b):
> # käsud


> Another example: too short section underline:

>   Lisanäited
>   --

> I'm not sure if this is problem in Sphinx or in docutils,

Docutils seems to work fine. After changing "sourcecode" to "code", I get
the following output from docutils SVN version::

  /tmp/umlaut.rst:3: (ERROR/3) Error in "code" directive:
  maximum 1 argument(s) allowed, 7 supplied.
  
  .. code:: python
  for i in range(a,b):
  # käsud
  
  
  /tmp/umlaut.rst:11: (WARNING/2) Title underline too short.
  
  Lisanäited
  --
  /tmp/umlaut.rst:11: (SEVERE/4) Unexpected section title.
  
  Lisanäited
  --
  Exiting due to level-4 (SEVERE) system message.

>  can't tell > from the stacktrace:


> Warning, treated as error:
> Traceback (most recent call last):
>   File "c:\python27\scripts\sphinx-build-script.py", line 8, in
>
> load_entry_point('Sphinx==1.0.7', 'console_scripts', 'sphinx-
> build')()
>   File "c:\python27\lib\site-packages\sphinx-1.0.7-py2.7.egg\sphinx
> \__init__.py"
> , line 67, in main
> return cmdline.main(argv)
>   File "c:\python27\lib\site-packages\sphinx-1.0.7-py2.7.egg\sphinx
> \cmdline.py",
>  line 212, in main
> print >>error, err
> UnicodeEncodeError: 'ascii' codec can't encode character u'\xe4' in
> position 202
>: ordinal not in range(128)

You might try to change line 212, in
c:\python27\lib\site-packages\sphinx-1.0.7-py2.7.egg\sphinx\cmdline.py

from 

> print >>error, err

to 

> print >>error, err.encode("utf-8")

or something more secure like

> print >>error, err.encode("ascii", "backslashreplace")

(in case the output stream does not know how to handle utf-8).

The idea is explained and used in more detail in Docutils'
error_reporting sub-module. See the diffs of `revision 7037`__
http://svn.berlios.de/viewvc/docutils?view=revision&revision=7037 for the
changes made in Docutils to overcome Python's error-reporting-encoding
problems.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Issue with .. note:: and similar

[Guenter Milde]

On 2011-08-30, Infinity77 wrote:
> On Aug 30, 9:51 am, Guenter Milde wrote:
>> On 2011-08-29, Infinity77 wrote:

>> > However, now I am getting this kind of errors:
>> > E:\AGW\agw\aui\auibook.py:docstring of
>> > aui.auibook.AuiNotebook.DeletePage:6: (ERROR/3) Error in "note"
>> > directive:
>> > invalid option block.

>> Are you perfectly sure the resulting markup is valid?


>> or a separate content block

>> :note:

>>     L{DeletePage} removes a tab from the multi-notebook, and
>>     destroys the window as well.


> Thank you for your suggestion. Unfortunately, the :note: is already a
> one-liner, it got mangled by the very smart (!) Google wrapping
> facility. I get the same error message even if I put something like:

>:note: hello

I suppose the problem is the mangling step.

Looking at the error, is see "invalid option block". This indicates that
the rst parser sees some option block, i.e. something like e.g.::

  .. note:: :note: a short note

or similar.

Do you have a chance to check what the "mangled" docstring looks like?

Did you try with valid rst in the docstring literal?


> Moreover, what is curious is that this approach has always worked from
> Sphinx -0.3 (yes, minus) up to Sphinx 1.0.7, it only breaks now with
> the pre-dev version.

> Oh, and another issue. 

Unfortunately, I cannot help with these.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Crash reports caused by non-ascii characters

[Guenter Milde]

On 2011-08-31, Ernesto Posse wrote:
> On Wed, Aug 31, 2011 at 3:38 PM, Aivar  wrote:
>> Hi!

>> In some cases, when I make syntax mistake in reST source and when
>> there is a non-ascii character around, I get stacktrace instead of
>> helpful message telling me where is the mistake. It's quite hard to
>> track down such mistakes.

>> One example is when I forget empty line after directive, for example:

>> .. sourcecode:: python
>>    for i in range(a,b):
>>        # käsud


>> Another example: too short section underline:

>>      Lisanäited
>>      --

>> I'm not sure if this is problem in Sphinx or in docutils, can't tell
>> from the stacktrace:

...

> In the example you are giving the message at the and of the trace is
> telling you exactly what the problem is: you included some non-ASCII
> character in a plain ASCII file. But this is not a Sphinx-specific
> issue. This is a general Python issue. This is not a bug in Sphinx (or
> Python): if you give as input a file with non-ASCII characters the
> correct behaviour is to raise an exception, as is the case here.

While the first example shows Python source code, both examples are from a
reStructuredText input file. Docutils and Sphinx both default to UTF-8 input
encoding (and allow to specify a different input encoding in the settings).

However, both Docutils and Sphinx also have (or had) problems with error
reporting due to the string/unicode conversions. Most of Docutils'
problems are solved in release 0.8. Some remaining ones as well as a
Sphinx incompatibility with LaTeX output are solved in the development
version. You might try with a Docutils  SVN checkout or daily snapshot.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Changing section numbering in HTML and Latex

[Guenter Milde]

On 2011-08-23, Gaël Varoquaux wrote:

> I have a biggish document written in Sphinx (yeah go go go Sphinx!):
> http://scipy-lectures.github.com/

> It has 'parts', and chapters below them, as you can see from the above page.

> So far the parts where just implemented as an extra layer of headers. The 
> problem is that it induces a heavily nested structured, with section numbers 
> such as 2.1.1.2.1.

> I'd like to:

> Either insert titles in the middle of the toc, as it is currently the case 
> on http://scipy-lectures.github.com/. These would act as part separators. It 
> tried by putting two toctree one after the other, but the number starts 
> again at 1 in each new toc.

> Either change the number on the parts to be capital alphabetic characters, 
> as in "A.1.1.2.1".

> Any suggestions on how to achieve similar goals?

The rst "sectnum" directive has options for the start number and a number
prefix.

I don't know, how this interacts with Sphinx document merging, though.

http://docutils.sf.net/docs/ref/rst/directives.html#automatic-section-numbering


Also, the Docutils LaTeX writer has a 

  --use-part-section  Add parts on top of the section hierarchy.

config setting, that in connection with 

  --no-section-numbering  Disable section numbering by Docutils.
  (i.e. enable numbering by LaTeX)
  
will use \part for the top section level.

Again, I don't know how this works out in Sphinx.

Günter  
  

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Issue with .. note:: and similar

[Guenter Milde]

On 2011-08-29, Infinity77 wrote:

> However, now I am getting this kind of errors:

> E:\AGW\agw\aui\auibook.py:docstring of
> aui.auibook.AuiNotebook.DeletePage:6: (ERROR/3) Error in "note"
> directive:
> invalid option block.

> Which is fantastically wrong as the "note" directive is perfectly
> valid:

>:note: L{DeletePage} removes a tab from the multi-notebook, and
> destroys the window as well.

> I pre-process the docstrings using this approach:

> def setup(app):

> app.connect('autodoc-process-docstring', mangle_docstrings)


> In which I replace the L{something} with an appropriate ReST link and
> I replace the ":note:" attribute with ".. note::" (I have to do this
> because of backward compatibility with epydoc).

> Now, I am not sure what has changed in Sphinx to make this happen, but
> I welcome any suggestion in order to fix this issue (I have many more
> errors related to ".. note::", ".. warning::" and friends.

Are you perfectly sure the resulting markup is valid?

Valid note directives
*

.. note:: This is a one line note

.. note:: This is a 
  two line note with indentation
  
.. note:: One space 
 indentation is enough
 
.. note::
   without argument is fine as well

.. note::

   with separate content block

Invalid note directives
***

.. note:: No indentation
is an error! 

.. note::
without argument and indentation
results in two errors.



In order to check, maybe you can replace the compatibility hack with valid
rst (at least temporarily). If it works with porperly indented notes, try
again with e.g.

:note: L{DeletePage} removes a tab from the multi-notebook, and
   destroys the window as well.
   
or 

:note: 
L{DeletePage} removes a tab from the multi-notebook, and
destroys the window as well.

a one-liner

:note: L{DeletePage} removes a tab from the multi-notebook, and destroys the 
window as well.
   
or a separate content block

:note: 

L{DeletePage} removes a tab from the multi-notebook, and
destroys the window as well.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Include other Sphinx projects as LaTex appendices

[Guenter Milde]

On 2011-08-20, Thomas wrote:

> I have to make a summary of multiple works which have all been
> documented using Sphinx, with a LaTex output.
> Those documentations must be inserted in my summary as appendices, but
> can't find a way to do that correctly.


> Is there a simple way to insert those documents as appendices ?

I don't know.

> If not, is there a simple way to create the appendices manually, by
> inserting a cleaned version of generated LaTex files to the summary
> one ?

You might try this kind of post processing: 

* in the generated *.tex files, strip all lines before and including
  ``\begin{document}`` and the line with ``\end{document}``
  
* in the "master file", add commands like::

  \input{firstappendix.tex}
  \input{secondappendix.tex}
  ...

  at the place the appendices should appear. Either as raw latex in the
  source or in a post-processing step.
  
> I've also thought about inserting those files in the toctree of my
> summary, but how can I indicate they should have a roman chapter
> number (A, B, ...) ?

Insert ``\appendix`` (as raw LaTeX) just before the \includes.

> Thanks for answers.
> Thomas


-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.

[sphinx-dev] Re: Image Cross-Referencing

[Guenter Milde]

On 2011-07-02, Gabor Bernat wrote:

> [-- Type: text/plain, Encoding: quoted-printable --]

> Relative like ..\x.html ?

> I was thinking of a way that could work from both HTML and PDF build.

Then you need two image elements, one for HTML and one for PDF with
the appropriate URLs and "only-*" or "no_*" class arguments so that the
writer skips the "wrong" one.

Günter

-- 
You received this message because you are subscribed to the Google Groups 
"sphinx-dev" group.
To post to this group, send email to sphinx-dev@googlegroups.com.
To unsubscribe from this group, send email to 
sphinx-dev+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/sphinx-dev?hl=en.