docutils-users Mailing List for Docutils: Documentation Utilities

On 2011-04-24, lu...@gm... wrote:

> Hello friends...

> How can I put *more than one blank line* in a rst file, to make a space
> between paragraphs ? (for use with rst2pdf...)
> ie.:

> """
> 1) First line of a list
>       A) Indented paragraph
>               i) kkk
> 2) Second line of a list
>       B) Indented...
>=2E....................................... *here I want more blank lines*=

> Another paragraph outside de list

> """

> Perhaps it's simple, ... but I don't know. Sorry!! :(

Docutils is not a typewriter. In the output you do not have "blank
lines" but configurable amount of vertical whitespace between
block-level elements. Hence, you cannot

  put *more than one blank line* in a rst file, to make a space
  between paragraphs 
  
in the output (except for literal or parsed-literal blocks).

But you can, e.g.:

a) apply a style to either the list or a paragraph following the list
   (I don't know details about styling for `rst2pdf (reportlab)`.)

b) Re-define the transition element as vertical whitespace in a style
   sheet. (There are examples for HTML and LaTeX styles in the sandbox.)
   
   Then you can separate paragraphs
   
   -----------------------
   
   with a transition.
   
   Using vertical whitespace instead of a horizontal line for a
   transition is common in books.


c) Put *more than one blank line* in a rst file, to make a prominent
   space between paragraphs in the rst source file (without affecting the
   output).
   
   Like several space characters in a paragraph, several blank lines
   between paragraphs are consolidated to one. This is like the
   whitespace handling in LaTeX and similar to HTML.



Günter

Good morning,

I'm not sure if this is a question better suited for -develop, as in
my experience -dev lists are for core hacking and not "extending"
questions such as my own. If that is a poor assumption, I apologize,
and let me know.

I have a need for a directive which, given a child bullet_list, yields
a section with three child nodes: its title, a preface paragraph, and
the bullet_list itself. So, like this:

    .. moreinfo:: More information

        - external link 1
        - external link 2

In the document, that would yield:

    <section>
        <title>
        <paragraph>
        <bullet_list>
            ...

My early attempt at this directive worked well, with one problem; in
the final document, the created section was considered a child of the
section immediately before. So I ended up with this:

    <section>
        ...
        <section>
            <title>
            ...

Knowing what I know about parsers, it seems to me that this is a
corner case in the section discovery logic, which makes sense. Is it
possible for a directive to specify that the section it emits is to be
a primary section that stands alone? Can a directive break sections
like that? Or will I be resorted to:

    More information
    ----------------

    .. moreinfo::

        - external link 1
        - external link 2

My initial rough stab at the directive follows. It's only my third
additional directive and I have worked from examples, so any feedback
welcome in addition to my question. Thanks!

    class MoreInfoDirective(Directive):
        """Registers the .. moreinfo:: directive, which marks up the
ext links"""
        required_arguments = 0
        optional_arguments = 1
        final_argument_whitespace = True
        option_spec = {}
        has_content = True

        def run(self):
            """Called by docutils when the directive is used"""
            self.assert_has_content()
            if len(self.arguments) == 0:
                section_title = "More information"
            else: section_title = " ".join(self.arguments)
            child_list = nodes.bullet_list("\n".join(self.content))
            self.state.nested_parse(self.content, self.content_offset,
child_list)
            disclaimer_text = "..."
            return [nodes.section(section_title,
                        nodes.title(section_title,
                            nodes.Text(section_title, section_title)),
                        nodes.paragraph(disclaimer_text,
                            nodes.Text(disclaimer_text, disclaimer_text)),
                        child_list, ids=["moreinfo"], classes=["moreinfo"])]

-- 
Jed Smith
je...@je...

check my question here

http://commondatastorage.googleapis.com/yunfan/doc/my-question-about-rst.html


PS: maybe you guys could tell me how to build my own library for this target
by docutils's exists api

On Mon, Apr 25, 2011 at 1:01 AM,  <lu...@gm...> wrote:
> Hello friends...
>
> How can I put *more than one blank line* in a rst file, to make a space
> between paragraphs ? (for use with rst2pdf...)
> I
> ie.:
>
> """
> 1) First line of a list
>        A) Indented paragraph
>                i) kkk
> 2) Second line of a list
>        B) Indented...
> ........................................ *here I want more blank lines*
> Another paragraph outside de list
>
> """

this looks like you need more vertical space after a list.
might be a stylesheet option.

anything else is a hack (e.g. verbatim with escaped blank , but i did not try)

> Perhaps it's simple, ... but I don't know. Sorry!! :(
>
> Rod
>
>
>
> ------------------------------------------------------------------------------
> Fulfilling the Lean Software Promise
> Lean software platforms are now widely adopted and the benefits have been
> demonstrated beyond question. Learn why your peers are replacing JEE
> containers with lightweight application servers - and what you can gain
> from the move. http://p.sf.net/sfu/vmware-sfemails
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
>



-- 
http://darefoot.blogspot.com

lu...@gm... writes:

> How can I put *more than one blank line* in a rst file

You can already, no? Just put the blank lines in; they will still
separate the two paragraphs.

> to make a space between paragraphs ? (for use with rst2pdf...) I ie.:

Ah, you're asking about how to *render* a larger-than-normal space
between paragraphs.

Could you set a class on one of the paragraphs, and apply a style for
that class which specifies the vertical space you want?

-- 
 \     “War is God's way of teaching geography to Americans.” —Ambrose |
  `\                                                            Bierce |
_o__)                                                                  |
Ben Finney

Hello friends...

How can I put *more than one blank line* in a rst file, to make a space
between paragraphs ? (for use with rst2pdf...)
I
ie.:

"""
1) First line of a list
	A) Indented paragraph
		i) kkk
2) Second line of a list
	B) Indented...
........................................ *here I want more blank lines*
Another paragraph outside de list

"""

Perhaps it's simple, ... but I don't know. Sorry!! :(

Rod

On 2011-04-19, Ross Rogers wrote:
> Veripool has System Verilog (SV) lex and yacc definitions.  The language is 
> pretty complex and the methods for determining which other files to 
> load into the parser are not straight-forward imports or #includes. 
> I'd really like to avoid rewriting the tokenizer and grammar in a 
> python format, but I want to use the magic of Sphinx to auto-generate SV 
> documentation.

> What would be the best way to bolt the existing parser into Sphinx/doc
> utils and generate reStructuredText?

> Should I try to provide some sort of Domain interface?  Or should I 
> simply generate Restructured Text myself?  Other options? 

I suppose that generating reStructuredText (one word as per decree of the
creator) in a preprocessor is the most straightforward solutions as long
as you do not require features that cannot be represented in rst.

There is a Python API to docutils, so you could feed a "Docutils doctree"
-- if there is a way to generate Python objects from your parser.

> [posted on this list per a suggestion on
> http://groups.google.com/group/sphinx-dev/browse_thread/thread/4f239cf313a91506
> ]

(I read the suggestion there but do not agree that the thread belongs to
Docutils.)

Günter

On Tue, Apr 19, 2011 at 04:37, James Hunt <jam...@ub...> wrote:
> The problem though is that my actual document does something like this:
>
> .. |foobar| image:: http://site.com/image.png
>   :alt: [image]
>
> ``mycommand`` |foobar|
> ----------------------
>
> Blah, blah.

Use an explicit hyperlink target
(http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#explicit-hyperlink-targets),
as Günter suggested already:


.. |foobar| image:: http://site.com/image.png
   :alt: [image]

.. _whatever you want to use as a reference:

``mycommand`` |foobar|
----------------------

Blah, blah.

Link to `whatever you want to use as a reference`_.

-- 
David Goodger <http://python.net/~goodger>

Veripool has System Verilog (SV) lex and yacc definitions.  The language is 
pretty complex and the methods for determining which other files to 
load into the parser are not straight-forward imports or #includes. 
I'd really like to avoid rewriting the tokenizer and grammar in a 
python format, but I want to use the magic of Sphinx to auto-generate SV 
documentation.

What would be the best way to bolt the existing parser into Sphinx/doc utils and 
generate reStructuredText?

Should I try to provide some sort of Domain interface?  Or should I 
simply generate Restructured Text myself?  Other options? 

 - Ross 

[posted on this list per a suggestion on http://groups.google.com/group/sphinx-
dev/browse_thread/thread/4f239cf313a91506]

Guenter Milde <milde <at> users.berlios.de> writes:

> 
> On 2011-04-18, James Hunt wrote:
> > Can anyone tell me how I can create an internal hyperlink to a section
> > title containing a replace:: (or indeed an image::) directive?
> 
> > For example:
> 
> > .. |foo| replace:: hello
> 
> > hello world |foo|
> > -----------------
> 
> > This is a section using a replace directive in the title. It expands
> > correctly, but doesn't seem to be "referencable"?
> 
> > Another section
> > ---------------
> 
> > See `hello world |foo|`_.
> 
> > This fails since the hyperlink target in the last line is invalid.
> > Presumably, this is because the "|foo|" replacement has already been
> > expanded? However, attempting to use the following also fails:
> 
> >   See `hello world hello`_.
> 
> You can check the HTML to see what anchor is placed in the section.
> 
> Or you can add an additional anchor like:
> 
> .. _hello:
> 
> hello world |foo|
> -----------------
> 
> Günter
Thanks Günter. I discovered that with no extra anchors, what does work is:

  See `hello world foo`_.

The problem though is that my actual document does something like this:

.. |foobar| image:: http://site.com/image.png
   :alt: [image]

``mycommand`` |foobar|
----------------------

Blah, blah.


So, whilst I can now create a reference to the mycommand section, the name of
the generated link is unexpected:

  See `mycommand foobar`_ 

This works, but the link name is then "mycommand foobar". However, "foobar"
isn't literal text - it expands to an image (or some alt image text).

So, maybe there is a subtle limitation here?:

  Implicit hyperlink targets containing directives which "expand" to
  a "null" text value, should not encode the directive name in the link.

Certainly, "See `mycommand`_ would make more sense intuitively for my particular
scenario.

I have found a slightly modified solution that works for me:

.. |foobar| image:: http://site.com/image.png
   :alt: image

``mycommand`` (|foobar|)
----------------------

Blah, blah.

Section
-------

See `mountall (foobar)`_.

This assumes of course that "foobar" is an "appropriate" name (in other words, a
word or phrase that makes logical sense for users when reading the document).

Regards,

James.

> 
> ------------------------------------------------------------------------------
> Benefiting from Server Virtualization: Beyond Initial Workload 
> Consolidation -- Increasing the use of server virtualization is a top
> priority.Virtualization can reduce costs, simplify management, and improve 
> application availability and disaster protection. Learn more about boosting 
> the value of server virtualization. http://p.sf.net/sfu/vmware-sfdev2dev
> _______________________________________________
> Docutils-users mailing list
> Docutils-users <at> lists.sourceforge.net
> https://lists.sourceforge.net/lists/listinfo/docutils-users
> 
> Please use "Reply All" to reply to the list.
> 

On 2011-04-18, Sebastián Magrí wrote:
> Hi people.

> Is there a way to get processed ReST output (without directives)
> having as input ReST with directives. I mean, given that I have a ReST
> file and I'm using csv-table to create a huge table, is it possible to
> get othet file with that huge table, and all other directives,
> expressed in ReST?

This would be one more use case for the rst writer (still to be
completed).

Günter

On 2011-04-18, James Hunt wrote:
> Can anyone tell me how I can create an internal hyperlink to a section
> title containing a replace:: (or indeed an image::) directive?

> For example:

> .. |foo| replace:: hello

> hello world |foo|
> -----------------

> This is a section using a replace directive in the title. It expands
> correctly, but doesn't seem to be "referencable"?

> Another section
> ---------------

> See `hello world |foo|`_.


> This fails since the hyperlink target in the last line is invalid.
> Presumably, this is because the "|foo|" replacement has already been
> expanded? However, attempting to use the following also fails:

>   See `hello world hello`_.

You can check the HTML to see what anchor is placed in the section.

Or you can add an additional anchor like:

.. _hello:

hello world |foo|
-----------------

Günter

Can anyone tell me how I can create an internal hyperlink to a section title
containing a replace:: (or indeed an image::) directive?

For example:

.. |foo| replace:: hello

hello world |foo|
-----------------

This is a section using a replace directive in the title. It expands correctly,
but doesn't seem to be "referencable"?

Another section
---------------

See `hello world |foo|`_.


This fails since the hyperlink target in the last line is invalid. Presumably,
this is because the "|foo|" replacement has already been expanded? However,
attempting to use the following also fails:

  See `hello world hello`_.

On Fri, Apr 15, 2011 at 01:31:59PM -0430, Sebastián Magrí wrote:
...
> That works, but as ReST syntax is sensible to white spaces and blank
> lines, it's kind off a mess to use Django's templating language there.
> That's why I want to use pseudoxml.

You can try to use Jinja2_ templating language: it uses almost the same
syntax as Django templates, and has more control over the generated
whitespace [1]_.

.. _Jinja2: http://jinja.pocoo.org/
.. [1] http://jinja.pocoo.org/docs/templates/#whitespace-control

-- 
Kirill Spitsin

Hi people.

Is there a way to get processed ReST output (without directives)
having as input ReST with directives. I mean, given that I have a ReST
file and I'm using csv-table to create a huge table, is it possible to
get othet file with that huge table, and all other directives,
expressed in ReST?

Regards...

-- 
Ing. Sebastián Ramírez Magrí
http://sebasmagri.com/

On 2011-04-15, Sebastián Magrí wrote:

> I wrote a XML template using pseudoxml/docutils_xml that is rendered
> using Django's render_to_string. I want to use the rendered XML as a
> doctree and generate the other formats using it.

> I've been trying to make it work using publish_doctree and
> publish_from_doctree methods without success as the string is parsed
> as ReST. Actually, and I hope to be able to change it soon,  I'm
> really rendering a ReST file that I pass to publish_doctree to get a
> doctree that is then passed to publish_from_doctree to generate ODT,
> HTML, S5 and Latex. That works, but as ReST syntax is sensible to
> white spaces and blank lines, it's kind off a mess to use Django's
> templating language there. That's why I want to use pseudoxml.

> Is it possible to do it that way? How should I do it? I would really
> appreciate  any advice here.

While pseudoxml is easier to read and write for humans, it is no
suitable input format, because it allows ambiguity.

xml if fine, but AFAIK, an XML->Docutils doctree parser needs still to
be written.

Günter

On 2011-04-16, Stefan Seefeld wrote:

> I'm using sphinx / rst to generate project documentation. Some of the 
> source rst files reference images that don't exist in the source tree, 
> i.e. that are being generated in the build process.

> Since I separate source and build trees, these images can't be found 
> with the normal lookup, i.e. relative to the source document location.

> Is there a way to configure or extend docutils to allow me to specify 
> additional search paths to be looked at to resolve such references ?

No.

Are you compiling with Sphinx or with both, Docutils and Sphinx (for
single documents vs. complete documentation)?

Are you generating HTML (should work, as images are only referenced)
or PDF (via LaTeX or via reportlab)?

Why not create the images in the source tree and let Sphinx (or the
makefile) move/link them to the build tree? Alternatively, move/link the
sources to the build tree too.

Günter

I cannot get the slide below to compile in rst2beamer.
It looks like a bug in handling the table
caption.  (rst2latex does fine.)

Alan


Test Slide
--------------------

.. csv-table:: Table 1
    :header-rows: 1
    :stub-columns: 1

    p1\\p2,0.0,0.2,0.4,0.6,0.8,1.0
    0.0,3.00,2.44,1.75,1.23,0.62,0.00
    0.2,3.39,2.81,2.03,1.46,0.85,0.24
    0.4,3.86,3.19,2.54,1.87,1.10,0.41

On Sat, Apr 16, 2011 at 13:24, Stefan Seefeld <st...@se...> wrote:
> On 2011-04-16 11:25, David Goodger wrote:
>> On Sat, Apr 16, 2011 at 07:07, Stefan Seefeld<st...@se...>  wrote:
>>> Hello,
>>>
>>> I'm using sphinx / rst to generate project documentation. Some of the
>>> source rst files reference images that don't exist in the source tree,
>>> i.e. that are being generated in the build process.
>>> Since I separate source and build trees, these images can't be found
>>> with the normal lookup, i.e. relative to the source document location.
>>>
>>> Is there a way to configure or extend docutils to allow me to specify
>>> additional search paths to be looked at to resolve such references ?
>> Not currently, no. Not built into Docutils anyhow; don't know about Sphinx.
>
> OK, thanks. What is the best approach to solve this, then, other than to
> copy the source tree into the build tree ? Do I need a custom directive
> where I can implement my own lookup rules ?

I have no opinion on this, sorry.

-- 
David Goodger <http://python.net/~goodger>

On 2011-04-16 11:25, David Goodger wrote:
> On Sat, Apr 16, 2011 at 07:07, Stefan Seefeld<st...@se...>  wrote:
>> Hello,
>>
>> I'm using sphinx / rst to generate project documentation. Some of the
>> source rst files reference images that don't exist in the source tree,
>> i.e. that are being generated in the build process.
>> Since I separate source and build trees, these images can't be found
>> with the normal lookup, i.e. relative to the source document location.
>>
>> Is there a way to configure or extend docutils to allow me to specify
>> additional search paths to be looked at to resolve such references ?
> Not currently, no. Not built into Docutils anyhow; don't know about Sphinx.

OK, thanks. What is the best approach to solve this, then, other than to 
copy the source tree into the build tree ? Do I need a custom directive 
where I can implement my own lookup rules ?

Thanks,
         Stefan


-- 

       ...ich hab' noch einen Koffer in Berlin...

On Sat, Apr 16, 2011 at 07:07, Stefan Seefeld <st...@se...> wrote:
> Hello,
>
> I'm using sphinx / rst to generate project documentation. Some of the
> source rst files reference images that don't exist in the source tree,
> i.e. that are being generated in the build process.
> Since I separate source and build trees, these images can't be found
> with the normal lookup, i.e. relative to the source document location.
>
> Is there a way to configure or extend docutils to allow me to specify
> additional search paths to be looked at to resolve such references ?

Not currently, no. Not built into Docutils anyhow; don't know about Sphinx.

-- 
David Goodger <http://python.net/~goodger>

Hello,

I'm using sphinx / rst to generate project documentation. Some of the 
source rst files reference images that don't exist in the source tree, 
i.e. that are being generated in the build process.
Since I separate source and build trees, these images can't be found 
with the normal lookup, i.e. relative to the source document location.

Is there a way to configure or extend docutils to allow me to specify 
additional search paths to be looked at to resolve such references ?

Thanks,
		Stefan


-- 

       ...ich hab' noch einen Koffer in Berlin...

On Fri, Apr 15, 2011 at 18:16, Alan G Isaac <ala...@gm...> wrote:
> The CSS in the default style is:
>
> p.attribution {
>   text-align: right ;
>   margin-left: 50% }
>
> Is that possibly a bug?

No, it's just the style that I liked at the time, when I wrote the
default stylesheet. Everyone is welcome to tweak it for themselves, or
replace it with their own. Style is subjective.

-- David

> It seems to have been chosen to match docbook (?),
> but I find the output bizarre.  The formatting I
> am familiar with would be left alignment,
> like here: http://projectmallard.org/1.0/mal_block_quote.html
> It gives better looking output, especially for short block
> quotes.
>
> I realize I can have what I want using CSS.
> I'm raising a question about the default style.
> Compare an extreme case (one line block quote):
>
>      Beauty is bought by judgement of the eye.
>      -- Shakespeare
>
>      Beauty is bought by judgement of the eye.
>                                                                                      -- Shakespeare
>
>
> fwiw,
> Alan Isaac

The CSS in the default style is:

p.attribution {
   text-align: right ;
   margin-left: 50% }

Is that possibly a bug?
It seems to have been chosen to match docbook (?),
but I find the output bizarre.  The formatting I
am familiar with would be left alignment,
like here: http://projectmallard.org/1.0/mal_block_quote.html
It gives better looking output, especially for short block
quotes.

I realize I can have what I want using CSS.
I'm raising a question about the default style.
Compare an extreme case (one line block quote):

      Beauty is bought by judgement of the eye.
      -- Shakespeare

      Beauty is bought by judgement of the eye.
                                                                                      -- Shakespeare


fwiw,
Alan Isaac

Hi people....

I'm working on a Django app and I basically want to be able to
display/export a document generated with data from the models in
several file formats. Actually, those formats supported by standard
docutils writers plus rst2pdf.

I wrote a XML template using pseudoxml/docutils_xml that is rendered
using Django's render_to_string. I want to use the rendered XML as a
doctree and generate the other formats using it.

I've been trying to make it work using publish_doctree and
publish_from_doctree methods without success as the string is parsed
as ReST. Actually, and I hope to be able to change it soon,  I'm
really rendering a ReST file that I pass to publish_doctree to get a
doctree that is then passed to publish_from_doctree to generate ODT,
HTML, S5 and Latex. That works, but as ReST syntax is sensible to
white spaces and blank lines, it's kind off a mess to use Django's
templating language there. That's why I want to use pseudoxml.

Is it possible to do it that way? How should I do it? I would really
appreciate  any advice here.

Regards...

-- 
Ing. Sebastián Ramírez Magrí
http://sebasmagri.com/