docutils-users — General discussions, questions, help requests.

Re: [Docutils-users] rst for library doc

[Chris G. <cl...@is...>]

On Mon, Feb 15, 2016 at 10:15:00AM +0000, Renato Pontefice wrote:
>    where  do can I look for ocumentation?
>    Renato
> 
It's not very extensive (it's a very simple plugin), but it's here:- 

    https://www.dokuwiki.org/plugin:rst


-- 
Chris Green

Re: [Docutils-users] rst for library doc

[Renato P. <ren...@gm...>]

where  do can I look for ocumentation?

Renato

Il giorno lun 15 feb 2016 alle ore 11:03 Chris Green <cl...@is...> ha
scritto:

> On Mon, Feb 15, 2016 at 09:58:16AM +0000, Renato Pontefice wrote:
> >    There are several wikis which can work with RST, a quick Google search
> >
> >      will turn up a few.
> >      I have written an RST plugin for Dokuwiki which is an excellent wiki
> >      for documentation.
> >      --
> >      Chris Green
> >
> >    Hi Chris, is this you plugin?
> >
> >      rst Plugin by chrsibsd
> >
> >    I've just seen and installed DW. I need to learn it a bit.
> >
> Yes, that's my plugin.  It's very simple, just uses the Docutils
> utilities to do the actual conversion from RST to HTML.  All my plugin
> does is hook the conversion into Docuwiki.
>
> --
> Chris Green
>
>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] rst for library doc

[Chris G. <cl...@is...>]

On Mon, Feb 15, 2016 at 09:58:16AM +0000, Renato Pontefice wrote:
>    There are several wikis which can work with RST, a quick Google search
> 
>      will turn up a few.
>      I have written an RST plugin for Dokuwiki which is an excellent wiki
>      for documentation.
>      --
>      Chris Green
> 
>    Hi Chris, is this you plugin?
> 
>      rst Plugin by chrsibsd
> 
>    I've just seen and installed DW. I need to learn it a bit.
> 
Yes, that's my plugin.  It's very simple, just uses the Docutils
utilities to do the actual conversion from RST to HTML.  All my plugin
does is hook the conversion into Docuwiki.

-- 
Chris Green

Re: [Docutils-users] rst for library doc

[Renato P. <ren...@gm...>]

There are several wikis which can work with RST, a quick Google search

> will turn up a few.
>
> I have written an RST plugin for Dokuwiki which is an excellent wiki
> for documentation.
>
> --
> Chris Green
>
Hi Chris, is this you plugin?


> rst Plugin by chrsibsd
>

I've just seen and installed DW. I need to learn it a bit.


>
> ------------------------------------------------------------------------------
> Site24x7 APM Insight: Get Deep Visibility into Application Performance
> APM + Mobile APM + RUM: Monitor 3 App instances at just $35/Month
> Monitor end-to-end web transactions and take corrective actions now
> Troubleshoot faster and improve end-user experience. Signup Now!
> http://pubads.g.doubleclick.net/gampad/clk?id=272487151&iu=/4140
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

Re: [Docutils-users] hyphen handling changed in references?

[Guenter M. <mi...@us...>]

On 2016-02-07, Alan G Isaac wrote:

> Fine Header
> ------------

> Am I wrong that I used to be able to refer to the
> `fine-header`_ (with hyphen) example above,
> and not just as `fine header`_ (no hyphen)?
> Memory glitch?

Why didn't you just try?

Running your example, I get:

/tmp/ss.rst:4: (ERROR/3) Unknown target name: "fine-header".


However, the HTML anchor uses the replacements as documented somewhere which
include spaces-to-hypens. Therefore, you get

<div class="document" id="fine-header">
<h1 class="title">Fine Header</h1>

and if you want to refer to this place without using rst
(e.g. inter-document links), you must use this, like in 
the link to the section "syntax highlight":

http://docutils.sourceforge.net/docs/user/config.html#syntax-highlight


Günter

Re: [Docutils-users] reStructuredText for notes, blogs, scientific articles and programming documentation?

[Guenter M. <mi...@us...>]

On 2016-02-13, Oleksandr Gavenko wrote:
> I am a long running ReST fan-boy 
...

... with a lot of questions.

Many of them can be answered by following the links in
http://docutils.sourceforge.net/docs/user/links.html

...


> But I don't understand how to get high quality printed output?

> "For dummies" book series have a lot of outlined notes and fanny styling. How
> that can be achieved? Do authors made own writer to Latex or Docbook and apply
> publisher styling?

> How well supported modern reader formats? fb2, epub, mobi?

Not with standard docutils. There is an epub writer in Sphinx.

>================================================================

> I would like to include foreign formats. What sources is good example for
> reference?

> What formats are already managed by ReST writers? lilypond (music notation),
> graphviz (graph), gnuplot (graphing), ImageMagick/GraphicsMagick?

No other source format is managed by standard docutils. You can include
images/graphics in a variety of vector and bitmap formats (see the docs).

Also, there are contributed extensions/pre-processors/frameworks for some
other input format inclusions.

>================================================================

> Can arbitrary code be run during document generation?

> Recently I see books/cources/sci reports like:

>   https://github.com/bcaffo/courses

> which uses "R Markdown":

>   http://rmarkdown.rstudio.com/

> So final document have result of running R language on pages.

> I would like to run Bash example.

> Or instead of afraid to make mistake place bc, octave-cli or R code and/or
> values in resulted document in place.

With standard docutils, you can use a Makefile to run/update examples that
generate files to include in rST.

There are contributed extensions/pre-processors/frameworks for some
other input format inclusions.

>================================================================

> Can literate programming be done in ReST?

There is a semi-literate framework:

  PyLit__ provides a bidirectional text <--> code converter for literate
  programming with reStructuredText.

  __ http://repo.or.cz/pylit.git

>================================================================

> Can I introduce foreign syntax in place, like:

>   ... see :man:`open(1)` and :man:`read(1)` ...

This would require a definition of the role "man".

>   ... pythagorean theorem is :math:`a^2 + b^2 = c^2` ...

This works out of the box.

>   ... :lisp:`(defun (x) ((lambda (y) (* y y)) x))` is better then
>       :java:`public static void main(String args[]) { }`

This would require a definition of custom roles
http://docutils.sourceforge.net/docs/ref/rst/directives.html#custom-interpreted-text-roles
(if you want syntax highlight, see 
http://docutils.sourceforge.net/docs/ref/rst/roles.html#code
).



> What writer are useful? 

Depends on the use-case.

> I check shpinx docs and see that I capable produce HTML with built-in JS
> search index for offline searching.

> Any other notable implementation?

Follow the links in http://docutils.sourceforge.net/docs/user/links.html

Günter

Re: [Docutils-users] rst for library doc

[Guenter M. <mi...@us...>]

On 2016-02-13, Renato Pontefice wrote:

> Hi,
> I'm still looking for "the best" way to build a documentation of the
> procedure program I use.

> I'm very inrested in .rst. Because of the way to produce HTML and .pdf
> output.
> But I still need a way to built docs, by more people. so I need (I think) a
> wiki as a container of that doc.

Alternatively, you might consider putting the rst-source under version
control. To me, this seems the easiest solution in case the program itself
is under version control and the programmers are the same people that also
should be able to work on the documentation, at least.

Günter

Re: [Docutils-users] Lout Writer?

[Guenter M. <mi...@us...>]

On 2016-02-08, Marcelo Huerta wrote:
> Matěj Cepl decía, en el mensaje "[Docutils-users] Lout Writer?" del 8/2/2016
> 10:52:21:

>> I have found in 
>> https://github.com/jimmykuu/reStInPeace/blob/master/to_lout.py 
>> something which looks like docutils (at least in some point in 
>> history, 2003?) supported output to Lout 
>> (http://savannah.nongnu.org/projects/lout). Is it true? Are the 
>> ruins of the code available somewhere?

> I didn't see that one, but in the sandbox there is a "lalo" folder containing
> a "lout_writer" project which is incomplete.

> http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/lalo/lout_writer/

As all sandbox code, this is not officially supported. Just give it a try...

Günter

Re: [Docutils-users] rst for library doc

[Chris G. <cl...@is...>]

On Sat, Feb 13, 2016 at 04:34:29PM +0100, renato wrote:
> Il giorno sab, 13/02/2016 alle 14.46 +0000, Chris Green ha scritto:
> > On Sat, Feb 13, 2016 at 01:53:42PM +0000, Renato Pontefice wrote:
> > >    Hi,
> > >    I'm still looking for "the best" way to build a documentation of
> > > the
> > >    procedure program I use.
> > >    I'm very inrested in .rst. Because of the way to produce HTML
> > > and .pdf
> > >    output.
> > >    But I still need a way to built docs, by more people. so I need
> > > (I
> > >    think) a wiki as a container of that doc.
> > >    Can someone sudgest me a way?
> > 
> > There are several wikis which can work with RST, a quick Google
> > search
> > will turn up a few.
> > 
> > I have written an RST plugin for Dokuwiki which is an excellent wiki
> > for documentation.
> > 
> Ok, I 've seen it. It seem very intresting. It has all the thing that
> I'm looking for. Now, I've to try it and try to write  .rst and export
> on html and pdf.
> Are there some sandbox that I can proof?
> 
Dokuwiki is quite simple to install if you have a server of your own,
alternatively a lot of hosting providers have it as a standard web
application to install from the control panel.

A basic Dokuwiki installation comes with a 'playground' area which is
a place to try things out.

... even better, the Dokuwiki home has a playground page:-

    https://www.dokuwiki.org/playground

-- 
Chris Green

Re: [Docutils-users] rst for library doc

[renato <ren...@gm...>]

Ok, I 've seen it. It seem very intresting. It has all the thing that
I'm looking for. Now, I've to try it and try to write  .rst and export
on html and pdf.
Are there some sandbox that I can proof?

Renato

Il giorno sab, 13/02/2016 alle 14.46 +0000, Chris Green ha scritto:
> On Sat, Feb 13, 2016 at 01:53:42PM +0000, Renato Pontefice wrote:
> >    Hi,
> >    I'm still looking for "the best" way to build a documentation of
> > the
> >    procedure program I use.
> >    I'm very inrested in .rst. Because of the way to produce HTML
> > and .pdf
> >    output.
> >    But I still need a way to built docs, by more people. so I need
> > (I
> >    think) a wiki as a container of that doc.
> >    Can someone sudgest me a way?
> 
> There are several wikis which can work with RST, a quick Google
> search
> will turn up a few.
> 
> I have written an RST plugin for Dokuwiki which is an excellent wiki
> for documentation.
> 

Re: [Docutils-users] rst for library doc

[Chris G. <cl...@is...>]

On Sat, Feb 13, 2016 at 01:53:42PM +0000, Renato Pontefice wrote:
>    Hi,
>    I'm still looking for "the best" way to build a documentation of the
>    procedure program I use.
>    I'm very inrested in .rst. Because of the way to produce HTML and .pdf
>    output.
>    But I still need a way to built docs, by more people. so I need (I
>    think) a wiki as a container of that doc.
>    Can someone sudgest me a way?

There are several wikis which can work with RST, a quick Google search
will turn up a few.

I have written an RST plugin for Dokuwiki which is an excellent wiki
for documentation.

-- 
Chris Green

[Docutils-users] rst for library doc

[Renato P. <ren...@gm...>]

Hi,
I'm still looking for "the best" way to build a documentation of the
procedure program I use.

I'm very inrested in .rst. Because of the way to produce HTML and .pdf
output.
But I still need a way to built docs, by more people. so I need (I think) a
wiki as a container of that doc.

Can someone sudgest me a way?

TIA

Renato

Re: [Docutils-users] reStructuredText for notes, blogs, scientific articles and programming documentation?

[Peter F. <pf...@ar...>]

TP wrote on Fri 12.02.2016 at 20:25:
> Well that was an amazingly rambling post that I won't even bother to
> quote, but will randomly answer :P
> 
> http://asciidoc.org/
> 
> http://asciidoctor.org/
> 
> https://atlas.oreilly.com/

Hmmm... 
Personally I like the reStructuredText markup better than AsciiDoc.

Especially in longer documents the section heading markup of AsciiDoc
looks too subtle compared to that of reStructuredText.

But this is a matter of taste and of personal preference and needs
not to be discussed here further.

Regards, Peter Funk
-- 
Peter Funk, home: ✉Oldenburger Str.86, D-27777 Ganderkesee
mobile:+49-179-640-8878 phone:+49-421-20419-0 <http://www.artcom-gmbh.de/>
office: ArtCom GmbH, ✉Haferwende 2, D-28357 Bremen, Germany

Re: [Docutils-users] reStructuredText for notes, blogs, scientific articles and programming documentation?

[TP <wi...@gm...>]

Well that was an amazingly rambling post that I won't even bother to
quote, but will randomly answer :P

http://asciidoc.org/

http://asciidoctor.org/

https://atlas.oreilly.com/

[Docutils-users] reStructuredText for notes, blogs, scientific articles and programming documentation?

[Oleksandr G. <gav...@gm...>]

I am a long running ReST fan-boy and uses markup mostly for managing personal tips:

  http://tips.defun.work/frame.html

and uses this notes mostly in text editor as remainder. But also publish them
online for personal advertising.

Also I use rst for personal projects man pages and documentation, for example:

  http://2048.defun.work/HACKING.html

================================================================

I checked specs of many plain text markup syntax and found that extensibility
presents only in ReST.

Most markups even can't handle TOCs or have scary syntax (like mediawiki) and
made without analysis:

  http://docutils.sourceforge.net/docs/dev/rst/alternatives.html
  http://docutils.sourceforge.net/docs/dev/rst/problems.html

expect resent efforts for CommonMark:

  http://spec.commonmark.org/

But CommonMark directly focused only on HTML output and any time you want
something special your should use HTML, like:

  <hr>

================================================================

My usage of ReST doesn't go far then styling python-docutils HTML output or
generating man pages.

I am interested in publishing.

Previously I take lessons directly from reading SVN source of
https://github.com/jacobian-archive/djangobook.com

Currently I see effort:

  https://github.com/mariuz/django-book
  http://django-book.readthedocs.org/en/latest/

This looks great in HTML.

But I don't understand how to get high quality printed output?

"For dummies" book series have a lot of outlined notes and fanny styling. How
that can be achieved? Do authors made own writer to Latex or Docbook and apply
publisher styling?

How well supported modern reader formats? fb2, epub, mobi?

================================================================

I would like to include foreign formats. What sources is good example for
reference?

What formats are already managed by ReST writers? lilypond (music notation),
graphviz (graph), gnuplot (graphing), ImageMagick/GraphicsMagick?

================================================================

Can arbitrary code be run during document generation?

Recently I see books/cources/sci reports like:

  https://github.com/bcaffo/courses

which uses "R Markdown":

  http://rmarkdown.rstudio.com/

So final document have result of running R language on pages.

I would like to run Bash example.

Or instead of afraid to make mistake place bc, octave-cli or R code and/or
values in resulted document in place.

================================================================

Can literate programming be done in ReST?

================================================================

Can I introduce foreign syntax in place, like:

  ... see :man:`open(1)` and :man:`read(1)` ...

  ... pythagorean theorem is :math:`a^2 + b^2 = c^2` ...

  ... :lisp:`(defun (x) ((lambda (y) (* y y)) x))` is better then
      :java:`public static void main(String args[]) { }`

================================================================

Can I define foreign expression elsewhere and put via reference in place?

================================================================

What writer are useful? 

I check shpinx docs and see that I capable produce HTML with built-in JS
search index for offline searching.

Any other notable implementation?

-- 
http://defun.work/

[Docutils-users] eol handling with start-after/end-before

[Alan G I. <ala...@gm...>]

I often use the ``include`` directive with the ``start-after``
and ``end-before`` options.  However, my delimiters are
generally on their own lines, which means that I end up with
undesired prepended and appended eols.  Is there any way
around this?

Thanks!




-- 
"I believe that anyone who claims to know what's going on
will lie about the little things too."
-- Sam Black Crow, in American Gods by Neil Gaiman, p.139

Re: [Docutils-users] Lout Writer?

[Marcelo H. <mar...@gm...>]

Matěj Cepl decía, en el mensaje "[Docutils-users] Lout Writer?" del 8/2/2016
10:52:21:

> I have found in 
> https://github.com/jimmykuu/reStInPeace/blob/master/to_lout.py 
> something which looks like docutils (at least in some point in 
> history, 2003?) supported output to Lout 
> (http://savannah.nongnu.org/projects/lout). Is it true? Are the 
> ruins of the code available somewhere?

I didn't see that one, but in the sandbox there is a "lalo" folder containing
a "lout_writer" project which is incomplete.

http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/sandbox/lalo/lout_writer/

-- 
   o-=< Marcelo >=-o

[Docutils-users] Lout Writer?

[Matěj C. <mc...@ce...>]

Hi,

I have found in 
https://github.com/jimmykuu/reStInPeace/blob/master/to_lout.py 
something which looks like docutils (at least in some point in 
history, 2003?) supported output to Lout 
(http://savannah.nongnu.org/projects/lout). Is it true? Are the 
ruins of the code available somewhere?

Best,

Matěj

-- 
https://matej.ceplovi.cz/blog/, Jabber: mc...@ce...
GPG Finger: 89EF 4BC6 288A BF43 1BAB  25C3 E09F EF25 D964 84AC
 
This message has been composed of recycled electrons. None of
these electrons has been harmed or injured in the creation and
transmission of this message but they have been shamelessly
exploited for this use.

[Docutils-users] hyphen handling changed in references?

[Alan G I. <ai...@am...>]

Fine Header
------------

Am I wrong that I used to be able to refer to the
`fine-header`_ (with hyphen) example above,
and not just as `fine header`_ (no hyphen)?
Memory glitch?

Thanks.

Re: [Docutils-users] New version of rst.el

[Dmitry S. <mi...@gm...>]

Hi Stefan!

Stefan Merten <stefan <at> merten-home.de> writes:
> Thanks for the reminder.
>
> This is indeed not a bug but a feature request: Definition lists are
> not supported yet. See the comment before `rst-line-tabs`::
>
>   ;; FIXME: Must consider other tabs:
>   ;;        * Line blocks
>   ;;        * Definition lists
>   ;;        * Option lists
>
> Definition lists seem extra hard to me - but frankly I never gave them
> a try.
>
> What to do in such a case?

[ Sorry for the late reply — actually I was not subscribed to this list so
missed your message. ]

If you think this is non-trivial to fix then you can probably ignore it (but
let's keep the bug open in case someone else decides to look at it).

I am not a user of Emacs or rst.el so this won't be me :)

--
Dmitry Shachnev

Re: [Docutils-users] New version of rst.el

[Stefan M. <st...@me...>]

Hi Dmitry!

3 days ago Dmitry Shachnev wrote:
> It would be very nice if you could look at
> https://sourceforge.net/p/docutils/bugs/283/ (which I have forwarded from
> Debian bug tracking system)?

Thanks for the reminder.

This is indeed not a bug but a feature request: Definition lists are
not supported yet. See the comment before `rst-line-tabs`::

  ;; FIXME: Must consider other tabs:
  ;;        * Line blocks
  ;;        * Definition lists
  ;;        * Option lists

Definition lists seem extra hard to me - but frankly I never gave them
a try.

What to do in such a case?


						Grüße

						Stefan

Re: [Docutils-users] New version of rst.el

[Dmitry S. <mi...@gm...>]

Hi Stefan,

Stefan Merten writes:
> Hi!
>
> I just released version V1.4.2 of rst.el:
>
http://sourceforge.net/p/docutils/code/HEAD/tree/trunk/docutils/tools/editors/emacs/rst.el

It would be very nice if you could look at
https://sourceforge.net/p/docutils/bugs/283/ (which I have forwarded from
Debian bug tracking system)?

--
Dmitry Shachnev

Re: [Docutils-users] some single quotes in code blocks, wrapped as error in html ouput

[Guenter M. <mi...@us...>]

On 2016-01-01, Jeff Hinrichs - DM&T wrote:

> Subject: some single quotes in code blocks, wrapped as error in html ouput

They are actually *highlighted* as "error" by pygments.

The reason seems to be, that you set the language to "python" but the code
block contains an interactive Python session or a doctest.
Pygments uses the language name "pycon" in this case:

.. code:: pycon

    >>> 'a' < 'b'
    True
    >>> type(5)
    <class 'int'>
    >>> type(5.0)
    <class 'float'>

> HTML: (rst2html)

works for me here.

> Escaping in a code block does not work,

Yes. Escaping only works in "parsed literal", but then you don't have syntax
highlight.


Günter

Re: [Docutils-users] exclamation mark in code block generates error tag around !

[Jeff H. - DM&T <je...@du...>]

Thank you, thank you.



On Fri, Jan 1, 2016 at 10:15 AM, Marc 'BlackJack' Rintsch <ma...@ri...>
wrote:

> On 01/01/16 15:57, Jeff Hinrichs - DM&T wrote:
> > rST:
> >
> > .. code:: python
> >
> >
> >     >>> print('Hello World!')
> >
> >     Hello World!
> >
> >     >>>
>
> The problem here is that you are trying to highlight code as Python
> source code which is a console session and not just Python source code.
>
> Pygments has a separate lexer for console sessions called `pycon`.  Try
> that one instead of `python`.
>
> Ciao,
>         Marc 'BlackJack' Rintsch
> --
> „A life is like a garden. Perfect moments can be had, but not preserved,
>  except in memory. LLAP” — Leonard Nimoy's last tweet.
>
>
>
> ------------------------------------------------------------------------------
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
>


-- 
Best,

Jeff Hinrichs
402.218.1473

Re: [Docutils-users] exclamation mark in code block generates error tag around !

[Marc 'B. R. <ma...@ri...>]

On 01/01/16 15:57, Jeff Hinrichs - DM&T wrote:
> rST:
> 
> .. code:: python                                                        
>                                                                            
> 
>     >>> print('Hello World!')                                          
>                                                                             
>     Hello World!                                                        
>                                                                            
>     >>> 

The problem here is that you are trying to highlight code as Python
source code which is a console session and not just Python source code.

Pygments has a separate lexer for console sessions called `pycon`.  Try
that one instead of `python`.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
„A life is like a garden. Perfect moments can be had, but not preserved,
 except in memory. LLAP” — Leonard Nimoy's last tweet.