[Docutils-users] Unicode bug when using Python 2 and a unicode quote character in a csv-table

[Philipp A. <flying-sheep@we...>]

Title explains it. Test case:

~~~

.. csv-table:: foobar
    :quote: ÷

    irrelevant

~~~

the bug is in parsers/rst/directives/tables.py, line 177:

self.quotechar = str(options['quote'])

when using python2, this causes python to try and decode it with the ASCII
codec, which fails.

if anyone tries to fix this, please look for similar instances to fix.

[Docutils-users] extracting metada about a rst document / directives

[Tomas Vondra <tv@fu...>]

Hi all,

I need to process rst documents using docutils - I got the basics
working (i.e. conversion into html etc.) but I'm a bit stuck with
extracting document metadata.

Each document has a few items on top - for example

:Date:      2014-02-28
:Published: no
:Author:    John Doe
:Slug:      this-is-my-first-doc
:Language:  en

And I need to extract this, so that I can process that - into a python
dictionary or something like that. I've noticed I could do extract that
from the doctree, but isn't there another - more straightforward way?

thanks
Tomas

Re: [Docutils-users] help with RAW directive to insert a text file

[David Goodger <goodger@py...>]

Note that "literalinclude" is a Sphinx-specific extension, and is NOT
a part of core Docutils:
http://sphinx-doc.org/markup/code.html#directive-literalinclude

Please include links to documentation in future, thanks.

DG

On 24 February 2014 09:52, Pete Jemian <jemian@...> wrote:
> Perhaps
>
> .. literalinclude:: ../gits/vcloud-management-tools/lib/application.rb
>     :linenos:
>     :language: guess
>
>
>
> On 2/23/2014 2:47 PM, Jorge wrote:
>> Hi there,
>>
>> I'm quite new to this stuff, I am trying to embed a plain text file into my
>> document using the raw directive. But can't figure out how to do this.
>>
>>
>> This is what I have in my .rst
>>
>> "
>> The code executed by this job is listed below:
>>
>> .. raw:: text
>>       :file: ../gits/vcloud-management-tools/lib/application.rb
>>
>> "
>>
>> How do I do this?
>>
>>
>> ------------------------------------------------------------------------------
>> Flow-based real-time traffic analytics software. Cisco certified tool.
>> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
>> Customize your own dashboards, set traffic alerts and generate reports.
>> Network behavioral analysis & security monitoring. All-in-one tool.
>> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
>> _______________________________________________
>> Docutils-users mailing list
>> Docutils-users@...
>> https://lists.sourceforge.net/lists/listinfo/docutils-users
>>
>> Please use "Reply All" to reply to the list.
>>
>
> --
> ----------------------------------------------------------
> Pete R. Jemian, Ph.D.                <jemian@...>
> Beam line Controls and Data Acquisition, Group Leader
> Advanced Photon Source,   Argonne National Laboratory
> Argonne, IL  60439                   630 - 252 - 3189
> -----------------------------------------------------------
>     Education is the one thing for which people
>        are willing to pay yet not receive.
> -----------------------------------------------------------
>
>
>
> ------------------------------------------------------------------------------
> Flow-based real-time traffic analytics software. Cisco certified tool.
> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
> Customize your own dashboards, set traffic alerts and generate reports.
> Network behavioral analysis & security monitoring. All-in-one tool.
> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
> _______________________________________________
> Docutils-users mailing list
> Docutils-users@...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

Re: [Docutils-users] help with RAW directive to insert a text file

[David Goodger <goodger@py...>]

On 23 February 2014 14:47, Jorge <jorge.costa@...> wrote:
> Hi there,
>
> I'm quite new to this stuff, I am trying to embed a plain text file into my
> document using the raw directive. But can't figure out how to do this.
>
>
> This is what I have in my .rst
>
> "
> The code executed by this job is listed below:
>
> .. raw:: text
>      :file: ../gits/vcloud-management-tools/lib/application.rb
>
> "
>
> How do I do this?

You're using the wrong directive. "raw" is to insert fragments that
are passed untouched to the final output. IOW, the format of the raw
fragment must match the document output format (e.g. HTML, LaTeX,
etc.).

You should be using the "include" directive with the "literal" or
"code" options. For details, see:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#include

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

Re: [Docutils-users] help with RAW directive to insert a text file

[Pete Jemian <jemian@an...>]

Perhaps

.. literalinclude:: ../gits/vcloud-management-tools/lib/application.rb
    :linenos:
    :language: guess



On 2/23/2014 2:47 PM, Jorge wrote:
> Hi there,
>
> I'm quite new to this stuff, I am trying to embed a plain text file into my
> document using the raw directive. But can't figure out how to do this.
>
>
> This is what I have in my .rst
>
> "
> The code executed by this job is listed below:
>
> .. raw:: text
>       :file: ../gits/vcloud-management-tools/lib/application.rb
>
> "
>
> How do I do this?
>
>
> ------------------------------------------------------------------------------
> Flow-based real-time traffic analytics software. Cisco certified tool.
> Monitor traffic, SLAs, QoS, Medianet, WAAS etc. with NetFlow Analyzer
> Customize your own dashboards, set traffic alerts and generate reports.
> Network behavioral analysis & security monitoring. All-in-one tool.
> http://pubads.g.doubleclick.net/gampad/clk?id=126839071&iu=/4140/ostg.clktrk
> _______________________________________________
> Docutils-users mailing list
> Docutils-users@...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

-- 
----------------------------------------------------------
Pete R. Jemian, Ph.D.                <jemian@...>
Beam line Controls and Data Acquisition, Group Leader
Advanced Photon Source,   Argonne National Laboratory
Argonne, IL  60439                   630 - 252 - 3189
-----------------------------------------------------------
    Education is the one thing for which people
       are willing to pay yet not receive.
-----------------------------------------------------------

[Docutils-users] help with RAW directive to insert a text file

[Jorge <jorge.costa@va...>]

Hi there,

I'm quite new to this stuff, I am trying to embed a plain text file into my 
document using the raw directive. But can't figure out how to do this. 

 
This is what I have in my .rst

"
The code executed by this job is listed below: 

.. raw:: text
     :file: ../gits/vcloud-management-tools/lib/application.rb

"

How do I do this?

Re: [Docutils-users] rst2pdf version 0.12.1 released

[Rajesh Jai <hellorajesh91@gm...>]

Re: [Docutils-users] citations: named in source, auto-numbered in result

[Matěj Cepl <mcepl@re...>]

Re: [Docutils-users] citations: named in source, auto-numbered in result

[Guenter Milde <milde@us...>]

On 2014-02-13, Zooko Wilcox-OHearn wrote:
> Dear Docutils folks:

> I want to spell my citations like this in the source: [Smith-2008]_,
> and then have them rendered as auto-numbers in the resulting html and
> pdf. My investigations so far have not indicated that this is
> implemented. Is that right?

This is not implemented in the core, but there are several extensions/hacks
that you can try.

> Would you be interested in maintaining this as an option in docutils?

My preference would be to have a citation system with a database for
references and automatic generation of the references list similar to
what LaTeX/BibTeX offers.

Have a look at
http://docutils.sourceforge.net/docs/dev/todo.html#footnote-citation-gathering
(and other places mentioning "citation" in this TODO file to see the
current state of pre-planning.

Günter

[Docutils-users] citations: named in source, auto-numbered in result

[Zooko Wilcox-OHearn <zooko@le...>]

Dear Docutils folks:

I want to spell my citations like this in the source: [Smith-2008]_,
and then have them rendered as auto-numbers in the resulting html and
pdf. My investigations so far have not indicated that this is
implemented. Is that right?

Would you be interested in maintaining this as an option in docutils?

Regards,

Zooko Wilcox-O'Hearn

Founder, CEO, and Customer Support Rep
https://LeastAuthority.com
Freedom matters.

Re: [Docutils-users] How do I put the project's version number in a hyperlink in the documentation

[Bert IJff <bert.ijff@vu...>]

David Goodger <goodger <at> python.org> writes:

> 
> That version substitution must be a Sphinx feature. It isn't part of
> Docutils itself.
> 
> As for interpolating the version number into a hyperlink, I don't
> think it's possible, sorry. But try on the Sphinx mailing list, maybe
> they can help.
> 


Good suggestion, David. Thanks, I'll give it a try.

Re: [Docutils-users] How do I put the project's version number in a hyperlink in the documentation

[David Goodger <goodger@py...>]

That version substitution must be a Sphinx feature. It isn't part of
Docutils itself.

As for interpolating the version number into a hyperlink, I don't
think it's possible, sorry. But try on the Sphinx mailing list, maybe
they can help.

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


On 5 February 2014 04:20, Bert IJff <bert.ijff@...> wrote:
> In my project's documentation I want to refer to 3 downloadable files by
> using hyperlinks.
> I found that I can specify the project's version number in the conf.py file,
> e.g.:
>     version = '1.3.2'
>
> Then I use |version| as a placeholder for the version number in the
> documentation e.g.
> #. Download http://www.domain.eu/download/part1-|version|.tar.gz and
>     $ sudo easy_install http://www.domain.eu/download/part2-|version|.tar.gz
> http://www.domain.eu/download/part3-|version|.tar.gz.
>
> Now the |version| part is replaced by the 1.3.2 but the hyperlink's href
> only contains the part on the left side of |version|.
>
> How can I make the "|version|.tar.gz" part be included in the hyperlink's href?
>
> Thanks for your help.
>
>
> ------------------------------------------------------------------------------
> Managing the Performance of Cloud-Based Applications
> Take advantage of what the Cloud has to offer - Avoid Common Pitfalls.
> Read the Whitepaper.
> http://pubads.g.doubleclick.net/gampad/clk?id=121051231&iu=/4140/ostg.clktrk
> _______________________________________________
> Docutils-users mailing list
> Docutils-users@...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.

[Docutils-users] How do I put the project's version number in a hyperlink in the documentation

[Bert IJff <bert.ijff@vu...>]

In my project's documentation I want to refer to 3 downloadable files by
using hyperlinks.
I found that I can specify the project's version number in the conf.py file,
e.g.:
    version = '1.3.2'

Then I use |version| as a placeholder for the version number in the
documentation e.g.
#. Download http://www.domain.eu/download/part1-|version|.tar.gz and
    $ sudo easy_install http://www.domain.eu/download/part2-|version|.tar.gz
http://www.domain.eu/download/part3-|version|.tar.gz. 

Now the |version| part is replaced by the 1.3.2 but the hyperlink's href
only contains the part on the left side of |version|.

How can I make the "|version|.tar.gz" part be included in the hyperlink's href?

Thanks for your help.

Re: [Docutils-users] docutils/rST vs direct html

[Pete Jemian <jemian@an...>]

It also fits inline program documentation easier than direct HTML or 
many other types of markup.

Another plus is that the syntax rules are so easy, it is a low barrier 
for collaborators to contribute.

Another consideration is that HTML might not be the target output.

On 1/26/2014 3:50 PM, Roberto Alsina wrote:
> On 26/01/14 16:31, Malik Rumi wrote:
>> Hello all,
>>
>> This is my first post. I just joined because I was led here by the
>> instructions for getting admindocs working on django. I looked around,
>> followed some links, and think I learned a lot. But I do have a question.
>>
>> My question is, why is rST any better than just putting the text in a
>> text editor and marking it up with html directly? Why would you chose
>> to use rST (or any 'lightweight markup language') instead? And I ask
>> that in all serious, trying to understand, as opposed to tying to
>> cause controversy.
>>
>>
>> Thanks for enlightening this newby.
>>
>>
>
> +---------------------+-------------------------------+
> | This is a table.    | It's not a big table. but it's|
> |                     | mine.                         |
> +---------------------+-------------------------------+
>
> <table><tr><td>This is a table</td><td>It's not a big
> table but it's mine</td></tr></table>
>
> ------------------------------------------------------------------------------
> CenturyLink Cloud: The Leader in Enterprise Cloud Services.
> Learn Why More Businesses Are Choosing CenturyLink Cloud For
> Critical Workloads, Development Environments & Everything In Between.
> Get a Quote or Start a Free Trial Today.
> http://pubads.g.doubleclick.net/gampad/clk?id=119420431&iu=/4140/ostg.clktrk
> _______________________________________________
> Docutils-users mailing list
> Docutils-users@...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

-- 
----------------------------------------------------------
Pete R. Jemian, Ph.D.                <jemian@...>
Beam line Controls and Data Acquisition, Group Leader
Advanced Photon Source,   Argonne National Laboratory
Argonne, IL  60439                   630 - 252 - 3189
-----------------------------------------------------------
    Education is the one thing for which people
       are willing to pay yet not receive.
-----------------------------------------------------------

Re: [Docutils-users] docutils/rST vs direct html

[Roberto Alsina <ralsina@ne...>]

On 26/01/14 16:31, Malik Rumi wrote:
> Hello all,
>
> This is my first post. I just joined because I was led here by the 
> instructions for getting admindocs working on django. I looked around, 
> followed some links, and think I learned a lot. But I do have a question.
>
> My question is, why is rST any better than just putting the text in a 
> text editor and marking it up with html directly? Why would you chose 
> to use rST (or any 'lightweight markup language') instead? And I ask 
> that in all serious, trying to understand, as opposed to tying to 
> cause controversy.
>
>
> Thanks for enlightening this newby.
>
>

+---------------------+-------------------------------+
| This is a table.    | It's not a big table. but it's|
|                     | mine.                         |
+---------------------+-------------------------------+

<table><tr><td>This is a table</td><td>It's not a big
table but it's mine</td></tr></table>

Re: [Docutils-users] docutils/rST vs direct html

[Alan G Isaac <aisaac@am...>]

On 1/26/2014 3:41 PM, Marc 'BlackJack' Rintsch wrote:
> The ”lightweight” markup languages are more suitable for humans to read
> and write


That's certainly a key reason: pretty much anyone
will be able to read it, without instruction.

My original reason was that I was submitting papers
to places some of which did not accept LaTeX, while
others did.  By using reST I could produce LaTeX or
HTML as needed.  (This was not quite as clean as I
hoped, since the no-LaTeX outlets generally wanted
Word (I kid you not).  Word's import of HTML left
much to be desired, and at the time the Word writer
for reST had too many missing features.  It was still
better than converting LaTeX however!

Alan

Re: [Docutils-users] docutils/rST vs direct html

[Marc 'BlackJack' Rintsch <marc@ri...>]

On 26/01/14 20:31, Malik Rumi wrote:
> My question is, why is rST any better than just putting the text in a
> text editor and marking it up with html directly? Why would you chose to
> use rST (or any 'lightweight markup language') instead? And I ask that
> in all serious, trying to understand, as opposed to tying to cause
> controversy.

The term `lightweight markup language` contains a hint: It is easier to
write text with some lightweight markup syntax than marking it up with
something ”heavy” like HTML.  Also easier to read, and therefore easier
to maintain.

You may try it yourself: Take each reST syntax construct and use it and
then write the same text directly in HTML.  See which markup is more
disruptive to the thinking and writing process and which is more error
prone.

The ”lightweight” markup languages are more suitable for humans to read
and write, while HTML is designed to be easy readable by the computer.
HTML has the additional ”problem” that it is, or at least was in the
beginning, meant to describe the layout and looks of the document while
for a human writer (and reader) semantics are more important for most
kind of documents.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“A programming language is low level when its
 programs require attention to the irrelevant.”
                              -- Alan J. Perlis

[Docutils-users] docutils/rST vs direct html

[Malik Rumi <malik.rumi@gm...>]

Hello all,

This is my first post. I just joined because I was led here by the
instructions for getting admindocs working on django. I looked around,
followed some links, and think I learned a lot. But I do have a question.

My question is, why is rST any better than just putting the text in a text
editor and marking it up with html directly? Why would you chose to use rST
(or any 'lightweight markup language') instead? And I ask that in all
serious, trying to understand, as opposed to tying to cause controversy.


Thanks for enlightening this newby.

Re: [Docutils-users] docutils.nodes.Node's source and line attributes

[Brecht Machiels <brecht@mo...>]

---- On Thu, 09 Jan 2014 00:58:45 +0100 David Goodger<goodger@...> wrote ---- 

 > On 6 January 2014 07:50, Brecht Machiels <brecht@...> wrote: 
 > > Hello, 
 > > 
 > > I'm using reStructuredText as an input format for RinohType [1]. Since I want to provide useful warning/error messages, I rely on the source, tagname and line attributes of the Node instances to point the user to the relevant location in the source file. 
 > > 
 > > I have noticed that not all Node instances have non-None source and/or line attributes. For example, the following nodes (among others) in the quickstart.txt [2] have missing data: 
 > > * literal_block at line 119: document is None 
 > > * enumerated_list at line 143: both document and line are None 
 > > * bullet_list at line 179: both document and line are None 
 > > * literal_block at line 193: document is None 
 > > * literal_block at line 236: document is None 
 > > 
 > > Some other literal_block nodes do have document set though. 
 > > 
 > > Is this normal behavior? 
 >  
 > Those attributes were originally meant for development and debugging 
 > purposes. They are not guaranteed to be present on all elements, 
 > although it would be nice if they were. You may consider it a bug. 
 > Feel free to submit a bug report. Patches are welcome. 

I have created a new ticket to track this bug: https://sourceforge.net/p/docutils/bugs/245/
As this is a fairly important feature for RinohType, I will probably get around to fixing this sometime soon.

I've had a quick look at the docutils code. It seems that the source and line attributes are set in the different methods corresponding to the different rST elements (states.py). I think it would be better to set these attributes at a higher lever, independent of the rST element type. However, I'm not sure where this should be implemented.

Best regards,
Brecht

Re: [Docutils-users] forcing heading levels

[David Goodger <goodger@py...>]

On 10 January 2014 14:52, Matthew Woehlke <mwoehlke.floss@...> wrote:
> On 2014-01-10 15:32, David Goodger wrote:
>
>> On 10 January 2014 14:19, Matthew Woehlke wrote:
>>>
>>> On 2014-01-10 15:03, David Goodger wrote:
>>>>
>>>> On 10 January 2014 13:46, Matthew Woehlke wrote:
>>>>>
>>>>>
>>>>> I have a really simple document like:
>>>>>
>>>>> Title
>>>>> =====
>>>>>
>>>>> Section
>>>>> -------
>>>>>
>>>>> ...text here...
>>>>>
>>>>> Section
>>>>> -------
>>>>>
>>>>> ...text here...
>>>>>
>>>>>
>>>>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>>>>> "Section"s.
>>>>>
>>>>> Is there any way to force reST to start headings at <h2>, or (less
>>>>> preferable) to skip automatic title detection?
>>>>>
>>>>> Note: This needs to be rendered by a system I don't control, so I can't
>>>>> just throw CSS at the problem.
>>>>
>>>>
>>>> Please see the FAQ:
>>>>
>>>>
>>>> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
>>>
>>>
>>> Sorry, but that is unhelpful. Again, I *don't control* the process used
>>> to
>>> generate HTML.
>>
>>
>> Re that "again": In your original email, I understood "render" in its
>> usual sense, i.e. "render HTML in the browser", and that's a common
>> enough issue to have a section in the FAQ. I was trying to be helpful.
>> Specificity earlier would have avoided the misunderstanding.
>
>
> Fair enough. Apologies for the confusion.
>
>
>>> Therefore, unless there is a way to specify configuration in
>>> the .rst itself (if there is, it's not documented obviously enough), I
>>> can't
>>> use either of the solutions in the FAQ (both of which I already knew
>>> about).
>>>
>>> I need a solution that can be implemented with *only* changes to the .rst
>>> input file.
>>
>>
>> That's not possible, sorry.
>>
>> Do you have control over the .docutils configuration file? If so, you
>> can specify the setting there.
>
>
> I'm not sure. I can place one in the same directory as my .rst, but I have
> no idea if it will be used.
>
>
>> What is the environment in which the HTML is being generated?
>
>
> It's a server that generates dynamic content by fetching an .rst file from a
> git repository and producing HTML on demand. (Vaguely similar idea to
> github's automatic rendering of .rst, but it's not github.)
>
> I probably *could* go monkey with the server if I really had to (it's an
> internal thing developed and run by a coworker), but a general patch risks
> breaking things for other people, and a location-specific hack is getting
> rather egregious.
>
> Modifying it to try to fetch a configuration file might be okay though.

That sounds like the simplest solution. You'll want a file called
"docutils.conf" in the same directory as your reST file.
For details, see
http://docutils.sourceforge.net/docs/user/config.html#configuration-files

>>> So far the best I have come up with is to add:
>>>
>>>   .. disable title promotion
>>>
>>> ...to the very beginning of the document (note the leading indent; the
>>> text
>>> after the comment is of course arbitrary). The rendering is tolerable but
>>> makes it impossible to have the first heading be a title, and adds a
>>> useless
>>> <blockquote> element to the resulting HTML.
>>
>>
>> You can use the "title" directive to specify a document title.
>
>
> Right. Alas, it has no effect (something about how the server generates the
> HTML ignores what reST would otherwise specify the title to be; it doesn't
> work with "real" titles either). It would be nice (but not critical) to have
> an <h1 class="title"> though instead of a plain <h1>.
>
> Thanks for the tip anyway.
>
>
>>> Given that this is apparently a common problem, it seems to me that there
>>> should be a way to handle this more gracefully in the reST syntax
>>> itself...
>>
>>
>> Your specific problem is not common at all. This is the first I've heard
>> of it.
>
>
> Really? There is a FAQ about how it...
>
> I may have a unique wrinkle,

It's the unique wrinkle that I've never seen before.

> but it seems to me it would be useful if there
> was a syntatic way to solve the FAQ.

Yes, it would, and that has come up before. But there are security
concerns, and ultimately it depends on somebody having enough round
tuits for implementation, which hasn't happened yet. See
http://docutils.sourceforge.net/docs/dev/todo.html#misc-settings

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

Re: [Docutils-users] forcing heading levels

[Matthew Woehlke <mwoehlke.floss@gm...>]

On 2014-01-10 15:32, David Goodger wrote:
> On 10 January 2014 14:19, Matthew Woehlke wrote:
>> On 2014-01-10 15:03, David Goodger wrote:
>>> On 10 January 2014 13:46, Matthew Woehlke wrote:
>>>>
>>>> I have a really simple document like:
>>>>
>>>> Title
>>>> =====
>>>>
>>>> Section
>>>> -------
>>>>
>>>> ...text here...
>>>>
>>>> Section
>>>> -------
>>>>
>>>> ...text here...
>>>>
>>>>
>>>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>>>> "Section"s.
>>>>
>>>> Is there any way to force reST to start headings at <h2>, or (less
>>>> preferable) to skip automatic title detection?
>>>>
>>>> Note: This needs to be rendered by a system I don't control, so I can't
>>>> just throw CSS at the problem.
>>>
>>> Please see the FAQ:
>>>
>>> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
>>
>> Sorry, but that is unhelpful. Again, I *don't control* the process used to
>> generate HTML.
>
> Re that "again": In your original email, I understood "render" in its
> usual sense, i.e. "render HTML in the browser", and that's a common
> enough issue to have a section in the FAQ. I was trying to be helpful.
> Specificity earlier would have avoided the misunderstanding.

Fair enough. Apologies for the confusion.

>> Therefore, unless there is a way to specify configuration in
>> the .rst itself (if there is, it's not documented obviously enough), I can't
>> use either of the solutions in the FAQ (both of which I already knew about).
>>
>> I need a solution that can be implemented with *only* changes to the .rst
>> input file.
>
> That's not possible, sorry.
>
> Do you have control over the .docutils configuration file? If so, you
> can specify the setting there.

I'm not sure. I can place one in the same directory as my .rst, but I 
have no idea if it will be used.

> What is the environment in which the HTML is being generated?

It's a server that generates dynamic content by fetching an .rst file 
from a git repository and producing HTML on demand. (Vaguely similar 
idea to github's automatic rendering of .rst, but it's not github.)

I probably *could* go monkey with the server if I really had to (it's an 
internal thing developed and run by a coworker), but a general patch 
risks breaking things for other people, and a location-specific hack is 
getting rather egregious.

Modifying it to try to fetch a configuration file might be okay though.

>> So far the best I have come up with is to add:
>>
>>   .. disable title promotion
>>
>> ...to the very beginning of the document (note the leading indent; the text
>> after the comment is of course arbitrary). The rendering is tolerable but
>> makes it impossible to have the first heading be a title, and adds a useless
>> <blockquote> element to the resulting HTML.
>
> You can use the "title" directive to specify a document title.

Right. Alas, it has no effect (something about how the server generates 
the HTML ignores what reST would otherwise specify the title to be; it 
doesn't work with "real" titles either). It would be nice (but not 
critical) to have an <h1 class="title"> though instead of a plain <h1>.

Thanks for the tip anyway.

>> Given that this is apparently a common problem, it seems to me that there
>> should be a way to handle this more gracefully in the reST syntax itself...
>
> Your specific problem is not common at all. This is the first I've heard of it.

Really? There is a FAQ about how it...

I may have a unique wrinkle, but it seems to me it would be useful if 
there was a syntatic way to solve the FAQ.

-- 
Matthew

Re: [Docutils-users] forcing heading levels

[David Goodger <goodger@py...>]

On 10 January 2014 14:19, Matthew Woehlke <mwoehlke.floss@...> wrote:
> On 2014-01-10 15:03, David Goodger wrote:
>
>> On 10 January 2014 13:46, Matthew Woehlke wrote:
>>>
>>> I have a really simple document like:
>>>
>>> Title
>>> =====
>>>
>>> Section
>>> -------
>>>
>>> ...text here...
>>>
>>> Section
>>> -------
>>>
>>> ...text here...
>>>
>>>
>>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>>> "Section"s.
>>>
>>> Is there any way to force reST to start headings at <h2>, or (less
>>> preferable) to skip automatic title detection?
>>>
>>> Note: This needs to be rendered by a system I don't control, so I can't
>>> just throw CSS at the problem.
>>
>>
>> Please see the FAQ:
>>
>> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why
>
>
> Sorry, but that is unhelpful. Again, I *don't control* the process used to
> generate HTML.

Re that "again": In your original email, I understood "render" in its
usual sense, i.e. "render HTML in the browser", and that's a common
enough issue to have a section in the FAQ. I was trying to be helpful.
Specificity earlier would have avoided the misunderstanding.

> Therefore, unless there is a way to specify configuration in
> the .rst itself (if there is, it's not documented obviously enough), I can't
> use either of the solutions in the FAQ (both of which I already knew about).
>
> I need a solution that can be implemented with *only* changes to the .rst
> input file.

That's not possible, sorry.

Do you have control over the .docutils configuration file? If so, you
can specify the setting there.

What is the environment in which the HTML is being generated?

> So far the best I have come up with is to add:
>
>  .. disable title promotion
>
> ...to the very beginning of the document (note the leading indent; the text
> after the comment is of course arbitrary). The rendering is tolerable but
> makes it impossible to have the first heading be a title, and adds a useless
> <blockquote> element to the resulting HTML.

You can use the "title" directive to specify a document title.

> Given that this is apparently a common problem, it seems to me that there
> should be a way to handle this more gracefully in the reST syntax itself...

Your specific problem is not common at all. This is the first I've heard of it.

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

Re: [Docutils-users] forcing heading levels

[Matthew Woehlke <mwoehlke.floss@gm...>]

On 2014-01-10 15:03, David Goodger wrote:
> On 10 January 2014 13:46, Matthew Woehlke wrote:
>> I have a really simple document like:
>>
>> Title
>> =====
>>
>> Section
>> -------
>>
>> ...text here...
>>
>> Section
>> -------
>>
>> ...text here...
>>
>>
>> This renders quite badly, as the "Title" is the same size (<h1>) as the
>> "Section"s.
>>
>> Is there any way to force reST to start headings at <h2>, or (less
>> preferable) to skip automatic title detection?
>>
>> Note: This needs to be rendered by a system I don't control, so I can't
>> just throw CSS at the problem.
>
> Please see the FAQ:
> http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why

Sorry, but that is unhelpful. Again, I *don't control* the process used 
to generate HTML. Therefore, unless there is a way to specify 
configuration in the .rst itself (if there is, it's not documented 
obviously enough), I can't use either of the solutions in the FAQ (both 
of which I already knew about).

I need a solution that can be implemented with *only* changes to the 
.rst input file.



So far the best I have come up with is to add:

  .. disable title promotion

...to the very beginning of the document (note the leading indent; the 
text after the comment is of course arbitrary). The rendering is 
tolerable but makes it impossible to have the first heading be a title, 
and adds a useless <blockquote> element to the resulting HTML.

Given that this is apparently a common problem, it seems to me that 
there should be a way to handle this more gracefully in the reST syntax 
itself...

-- 
Matthew

Re: [Docutils-users] forcing heading levels

[David Goodger <goodger@py...>]

On 10 January 2014 13:46, Matthew Woehlke
<mw_triad@...> wrote:
> I have a really simple document like:
>
> Title
> =====
>
> Section
> -------
>
> ...text here...
>
> Section
> -------
>
> ...text here...
>
>
> This renders quite badly, as the "Title" is the same size (<h1>) as the
> "Section"s.
>
> Is there any way to force reST to start headings at <h2>, or (less
> preferable) to skip automatic title detection?
>
> Note: This needs to be rendered by a system I don't control, so I can't
> just throw CSS at the problem.

Please see the FAQ:
http://docutils.sourceforge.net/FAQ.html#unexpected-results-from-tools-rst2html-py-h1-h1-instead-of-h1-h2-why

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

[Docutils-users] forcing heading levels

[Matthew Woehlke <mw_triad@us...>]

I have a really simple document like:

Title
=====

Section
-------

...text here...

Section
-------

...text here...


This renders quite badly, as the "Title" is the same size (<h1>) as the 
"Section"s.

Is there any way to force reST to start headings at <h2>, or (less 
preferable) to skip automatic title detection?

Note: This needs to be rendered by a system I don't control, so I can't 
just throw CSS at the problem.

-- 
Matthew