docutils-develop Mailing List for Docutils: Documentation Utilities

On 2015-04-27, Tony Narlock wrote:
> On Sun, Apr 26, 2015 at 9:22 AM, engelbert gruber 
> <eng...@gm...> wrote:

>> currently i can do docutils maintenance with a python installation
>> without the need to get pip easyinstall setuptools wheels and ssl and
...
>> and how much of this burden will hit through to the user ?

> Non-technical end-users can't be expected to overcome the hurdles of not
> having virtualenv, pip and sphinx support.

Non-technical end-users are not expected to test Docutils on all supported
versions. Continued support for versions they don't have will not stand in
their way.

> If we do continue to support and Python 2.4 and 2.5 for the next few
> releases, I think we should reflect it's best effort basis, noting the
> python project (cpython), pip, virtualenv and sphinx (a tool popular
> package that uses docutils') dropped support.

This sentence, I do not understand. What does "reflect it is best effort
basis" mean? Could you please reformulate?

...

>> On 26 April 2015 at 15:51, Aahz <aa...@py...> wrote:

...

Why do you quote Aahz here, without reply/addition to his point?

Thanks,

Günter

On Tue, 28 Apr 2015 23:33:27 +0200, Guenter Milde <mi...@us...>  
wrote:

> On 2015-04-28, Brecht Machiels wrote:
>
>> RinohType can render a structured text document (only reStructuredText
>> at the moment) to a PDF based on a document template and a style sheet.
>
> There is a contributed PDF writer and rst2pdf.py front-end based on
> "reportlab" for many years. It used to be in the sandbox and moved to a
> separate host eventually...
>
> rst2odf + LibreOffice provides another alternative route to PDF.

I know there are alternatives. What is your point?

I did try to use the rst2pdf Sphinx builder a while ago. It produced a  
corrupt PDF and it seems to abandoned by the developer, so I don't think  
rst2pdf can be recommended at the moment.

>> It should be able to replace the Sphinx LaTeX builder eventually.
>
> LaTeX comprises typesetting experience of dekades. RT may provide an
> quick and easy alternative eventually, but replacement? I doubt it.

LaTeX has many problems worth fixing. But you are free to doubt, of course.
Luckily, the availability of RinohType does not affect the LaTeX option in  
any way, so you can just keep on using that.

I don't expect you to be enthusiastic about RinohType. But if you can't  
provide any useful feedback, please refrain from replying to announcements  
like this.

Brecht

On 2015-04-28, Brecht Machiels wrote:

> RinohType can render a structured text document (only reStructuredText
> at the moment) to a PDF based on a document template and a style sheet.

There is a contributed PDF writer and rst2pdf.py front-end based on
"reportlab" for many years. It used to be in the sandbox and moved to a
separate host eventually...

rst2odf + LibreOffice provides another alternative route to PDF.

> It should be able to replace the Sphinx LaTeX builder eventually.

LaTeX comprises typesetting experience of dekades. RT may provide an
quick and easy alternative eventually, but replacement? I doubt it.

> Compared to LaTeX, it greatly simplifies the creation of custom document  
> templates and style sheets.

Günter

Hi Gamesbrainiac!

Yesterday Gamesbrainiac wrote:
> Is there a tool that automatically converts a rst file to an rst file with
> the proper line width, retaining the correct formatting (indentation etc).

Two ideas come to mind which may help.

1. Use a workflow including `xml2rst` (see sandbox)

   `xml2rst` has an option to set the line width for text.

2. Use `rst-mode` in Emacs

   `rst-mode` supports filling of lines and you may fill a single
   paragraph or whole regions. I'm not sure what it may break,
   however. Be careful with tables and literal text. Plain text,
   lists, and so own should work like a charm.


						Grüße

						Stefan

On Mon, 27 Apr 2015 22:49:04 +0200, Aahz <aa...@py...> wrote:

> On Mon, Apr 27, 2015, Brecht Machiels wrote:
>>
>> RinohType is a document processor inspired by LaTeX and written in  
>> Python.
>> Version 0.1.1 is the first release and is incomplete and very buggy.
>> Nonetheless, it should be able to render most reStructuredText files and
>> it also includes a Sphinx builder.
>
> I'm confused.  What value does RinohType add over straight Docutils or
> Sphinx?  I suggest posting your answer somewhere on your project and
> replying with a link; I can't be the only person who doesn't get it.

RinohType can render a structured text document (only reStructuredText at  
the moment) to a PDF based on a document template and a style sheet. It  
should be able to replace the Sphinx LaTeX builder eventually.

Compared to LaTeX, it greatly simplifies the creation of custom document  
templates and style sheets.

I will update the package's description on PyPI to make this more clear.

Best regards,
Brecht

On Mon, Apr 27, 2015, Brecht Machiels wrote:
> 
> RinohType is a document processor inspired by LaTeX and written in Python.
> Version 0.1.1 is the first release and is incomplete and very buggy.
> Nonetheless, it should be able to render most reStructuredText files and
> it also includes a Sphinx builder.

I'm confused.  What value does RinohType add over straight Docutils or
Sphinx?  I suggest posting your answer somewhere on your project and
replying with a link; I can't be the only person who doesn't get it.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Reality is that which, when you stop believing in it, doesn't go away."
--Philip K. Dick

Hello,

RinohType is a document processor inspired by LaTeX and written in Python.
Version 0.1.1 is the first release and is incomplete and very buggy.
Nonetheless, it should be able to render most reStructuredText files and
it also includes a Sphinx builder.

You can read more about RinohType here:
http://www.mos6581.org/rinohtype_status_update_1
And the PyPI link: https://pypi.python.org/pypi/RinohType/0.1.1

Bug reports and other feedback are highly appreciated.

Best regards,
Brecht Machiels

Hi there!

Is there a tool that automatically converts a rst file to an rst file with
the proper line width, retaining the correct formatting (indentation etc).

I ask because I'm about to make one, since I couldn't find a suitable tool
(and I don't want to waste my time making something that already exists)

-- 
Kind Regards,

Quazi Nafiul Islam

My rationale / data has been stated earlier in the thread. I have nothing
to add.

On Sun, Apr 26, 2015 at 9:22 AM, engelbert gruber <
eng...@gm...> wrote:

> currently i can do docutils maintenance with a python installation
> without the need to get pip easyinstall setuptools wheels and ssl and


> and how much of this burden will hit through to the user ?
>
Non-technical end-users can't be expected to overcome the hurdles of not
having virtualenv, pip and sphinx support.

If we do continue to support and Python 2.4 and 2.5 for the next few
releases, I think we should reflect it's best effort basis, noting the
python project (cpython), pip, virtualenv and sphinx (a tool popular
package that uses docutils') dropped support.

>
> cheers
>
> On 26 April 2015 at 15:51, Aahz <aa...@py...> wrote:
> > On Sun, Apr 26, 2015, Tony Narlock wrote:
> >>
> >> However, you're currently most active contributor here  [...]
> >
> > Making a small digression about the way typical Open Source projects
> > work and particularly the way this one works:
> >
> > David Goodger is the originator and dictator.  Docutils is small enough
> > that basically everything still needs to get approved by him.  Activity
> > is only a small measure of the extent to which he delegates authority;
> > much more important is whether you prove with contributions over an
> > extended period of time that you understand the Docutils philosophy and
> > code.
> >
> > I don't know whether you're deliberately or unconsciously trying to
> > change the Docutils social/political structure, but I guarantee you that
> > attempts to push such changes implicitly are much more likely to fail
> > and engender pushback.  (Not that explicitly addressing such changes is
> > significantly more likely to succeed, but the annoyance factor is
> > generally smaller per unit of push, assuming a reasonable amount of
> > politeness.)
> > --
> > Aahz (aa...@py...)           <*>
> http://www.pythoncraft.com/
> >
> > "Reality is that which, when you stop believing in it, doesn't go away."
> > --Philip K. Dick
> >
> >
> ------------------------------------------------------------------------------
> > One dashboard for servers and applications across Physical-Virtual-Cloud
> > Widest out-of-the-box monitoring support with 50+ applications
> > Performance metrics, stats and reports that give you Actionable Insights
> > Deep dive visibility with transaction tracing using APM Insight.
> > http://ad.doubleclick.net/ddm/clk/290420510;117567292;y
> > _______________________________________________
> > Docutils-develop mailing list
> > Doc...@li...
> > https://lists.sourceforge.net/lists/listinfo/docutils-develop
> >
> > Please use "Reply All" to reply to the list.
>
>
> ------------------------------------------------------------------------------
> One dashboard for servers and applications across Physical-Virtual-Cloud
> Widest out-of-the-box monitoring support with 50+ applications
> Performance metrics, stats and reports that give you Actionable Insights
> Deep dive visibility with transaction tracing using APM Insight.
> http://ad.doubleclick.net/ddm/clk/290420510;117567292;y
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

currently i can do docutils maintenance with a python installation
without the need to get pip easyinstall setuptools wheels and ssl and

and how much of this burden will hit through to the user ?

cheers

On 26 April 2015 at 15:51, Aahz <aa...@py...> wrote:
> On Sun, Apr 26, 2015, Tony Narlock wrote:
>>
>> However, you're currently most active contributor here  [...]
>
> Making a small digression about the way typical Open Source projects
> work and particularly the way this one works:
>
> David Goodger is the originator and dictator.  Docutils is small enough
> that basically everything still needs to get approved by him.  Activity
> is only a small measure of the extent to which he delegates authority;
> much more important is whether you prove with contributions over an
> extended period of time that you understand the Docutils philosophy and
> code.
>
> I don't know whether you're deliberately or unconsciously trying to
> change the Docutils social/political structure, but I guarantee you that
> attempts to push such changes implicitly are much more likely to fail
> and engender pushback.  (Not that explicitly addressing such changes is
> significantly more likely to succeed, but the annoyance factor is
> generally smaller per unit of push, assuming a reasonable amount of
> politeness.)
> --
> Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/
>
> "Reality is that which, when you stop believing in it, doesn't go away."
> --Philip K. Dick
>
> ------------------------------------------------------------------------------
> One dashboard for servers and applications across Physical-Virtual-Cloud
> Widest out-of-the-box monitoring support with 50+ applications
> Performance metrics, stats and reports that give you Actionable Insights
> Deep dive visibility with transaction tracing using APM Insight.
> http://ad.doubleclick.net/ddm/clk/290420510;117567292;y
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.

On Sun, Apr 26, 2015, Tony Narlock wrote:
>
> However, you're currently most active contributor here  [...]

Making a small digression about the way typical Open Source projects
work and particularly the way this one works:

David Goodger is the originator and dictator.  Docutils is small enough
that basically everything still needs to get approved by him.  Activity
is only a small measure of the extent to which he delegates authority;
much more important is whether you prove with contributions over an
extended period of time that you understand the Docutils philosophy and
code.

I don't know whether you're deliberately or unconsciously trying to
change the Docutils social/political structure, but I guarantee you that
attempts to push such changes implicitly are much more likely to fail
and engender pushback.  (Not that explicitly addressing such changes is
significantly more likely to succeed, but the annoyance factor is
generally smaller per unit of push, assuming a reasonable amount of
politeness.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

"Reality is that which, when you stop believing in it, doesn't go away."
--Philip K. Dick

Hey Günter! :)

I still disagree. This does unfortunately step in the way of cleanups and
tooling I want do, I'm disappointed because it does leave me out. It looks
like we won't be seeing clean python 3 compatibility, improved testrunners
or setuptools for a year or maybe longer.

However, you're currently most active contributor here (even compared to me
on sandboxes), so it looks like we're going to release the new HTMLWriter on
2.4 and 2.5. Let's make sure we do everything we can to make sure
HTMLWriter is stable and in good shape before our next release. :D

I'll continue to polish up documentation for how people on newer Linux
machines can install older python interpreters.

P.S.  Jessie is out today! :) https://www.debian.org/News/2015/20150426

On Thu, Apr 23, 2015 at 11:54 AM, Guenter Milde <mi...@us...> wrote:

> On 2015-04-21, Tony Narlock wrote:
> > On Tue, Apr 21, 2015 at 4:20 AM, Guenter Milde <mi...@us...>
> wrote:
> >> On 2015-04-20, Tony Narlock wrote:
> >> > On Mon, Apr 20, 2015 at 1:40 PM, Guenter Milde <mi...@us...>
> >> wrote:
> >> >> On 2015-04-20, Tony Narlock wrote:
>
> >> >> > The consensus seems to be desiring to *keep* python 2.4 support,
>
> ... for 0.13 and raise this to 2.5 for 0.14 onwards.
>
> >> * Evidence in the thread suggests that even 2.4 is still common in some
> >>   contexts.
>
> > They're installed on systems because they're a requirement for internal
> > utilities to the distribution.
>
> ... or packages/programs shipped with the distribution.
>
>
> We have to to distinguish between several user profiles:
>
> end users
>   often have no means to update Python but still may prefer a Docutils
>   version with bugs fixed. Examples are
>
>   * people working on someone elses system (employer, client, school),
>   * users with old hardware, small, and embedded systems (tablets, PDA).
>
>   Docutils is a tool suited for these people:
>
>   Docutils is pure Python code and can be installed in userspace.
>   Docutils is small and ressource-friendly.
>
>   -> there are valid use cases for a new Docutils version on old Python
>   versions.
>
> developers using Docutils
>   can use it with whatever Python version they have installed.
>
> Docutils contributors
>   can test under whatever versions they have. They may be asked to modify
>   their patches/contributions in order to be compatible with all
>   supported versions. This is usually just one of many edits required to
>   get the code in form.
>
>   Sandbox projects are under the responsibility of their respective
> authors.
>   They may have different requirements (including supported Python
> versions).
>
> Docutils developers
>   are expected to test their contributions across all supported versions,
>   especially the egde cases (minimal and maximal supported).
>   None of the active developers reported this as a problem.
>
> ...
>
> > To be honest, within this ~1% sampling of old /
> > exotic python releases / spam bots, it's more likely 0 people have any
> care
> > for new feature releases of docutils.
>
> This is easy to disprove: My N810 tablet runs Python 2.5 without a newer
> version available (short of self compiling). It will never appear in any of
> the statistics you referenced. Still, I am interested in
> running my HTML writer on it and I am interested in having my bugfixes
> available on it, too.
>
I have an N900. :)  But really, are you using docutils on it? And if you
are, do you absolutely *have* to have your HTMLWriter?

Ok. For the sake of your N810 and my N900. +1

>
> This is 1 person for continued support vs. 1 person for cutting it.  This
> is all we know for sure, as noone else took an unequivocal stand and
> there can only be speculation on how many people sharing our restrictions
> or positions we are speaking for.
>
I support you. It's not me vs you. You know more about docutils and have
more activity than me at this point. :) So I will share my perspective, but
probably will side with you if you so insist.

>
> But after all this is not about numbers but factual arguments:
>
> The current repository version passes alltests.py under versions 2.4,
> ..., 2.7 as well as 3.1, ..., 3.4.
>
> There is no feature hold back due to 2.4, 2.5, 3.1, or 3.2 incompatibility.
>
Yes, I want to implement setuptools and improved python  3.x support
(meaning we need 2.6 __future__'s).

grubert's wheels.

>
> There is no confirmed bug due to 2.4, 2.5, 3.1, or 3.2 incompatibility.
>
The graph shown the usage is extraordinarily low.

Within that because they are probably bots / locked into old, stable
releases.

>
> I can't see a compelling reason for cutting support for one or more
> versions before releasing the state of the art.
>

> Günter
>
>
>
> ------------------------------------------------------------------------------
> BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
> Develop your own process in accordance with the BPMN 2 standard
> Learn Process modeling best practices with Bonita BPM through live
> exercises
> http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual-
> event?utm_
> source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

On 2015-04-21, Tony Narlock wrote:
> On Tue, Apr 21, 2015 at 4:20 AM, Guenter Milde <mi...@us...> wrote:
>> On 2015-04-20, Tony Narlock wrote:
>> > On Mon, Apr 20, 2015 at 1:40 PM, Guenter Milde <mi...@us...>
>> wrote:
>> >> On 2015-04-20, Tony Narlock wrote:

>> >> > The consensus seems to be desiring to *keep* python 2.4 support,

... for 0.13 and raise this to 2.5 for 0.14 onwards.

>> * Evidence in the thread suggests that even 2.4 is still common in some
>>   contexts.

> They're installed on systems because they're a requirement for internal
> utilities to the distribution.

... or packages/programs shipped with the distribution.


We have to to distinguish between several user profiles:

end users
  often have no means to update Python but still may prefer a Docutils
  version with bugs fixed. Examples are

  * people working on someone elses system (employer, client, school),
  * users with old hardware, small, and embedded systems (tablets, PDA).
  
  Docutils is a tool suited for these people:

  Docutils is pure Python code and can be installed in userspace.
  Docutils is small and ressource-friendly.

  -> there are valid use cases for a new Docutils version on old Python
  versions.

developers using Docutils
  can use it with whatever Python version they have installed.

Docutils contributors
  can test under whatever versions they have. They may be asked to modify
  their patches/contributions in order to be compatible with all
  supported versions. This is usually just one of many edits required to
  get the code in form.

  Sandbox projects are under the responsibility of their respective authors.
  They may have different requirements (including supported Python versions).

Docutils developers
  are expected to test their contributions across all supported versions,
  especially the egde cases (minimal and maximal supported).
  None of the active developers reported this as a problem.

...

> To be honest, within this ~1% sampling of old /
> exotic python releases / spam bots, it's more likely 0 people have any care
> for new feature releases of docutils.

This is easy to disprove: My N810 tablet runs Python 2.5 without a newer
version available (short of self compiling). It will never appear in any of
the statistics you referenced. Still, I am interested in
running my HTML writer on it and I am interested in having my bugfixes
available on it, too. 

This is 1 person for continued support vs. 1 person for cutting it.  This
is all we know for sure, as noone else took an unequivocal stand and
there can only be speculation on how many people sharing our restrictions
or positions we are speaking for.

But after all this is not about numbers but factual arguments:

The current repository version passes alltests.py under versions 2.4,
..., 2.7 as well as 3.1, ..., 3.4. 

There is no feature hold back due to 2.4, 2.5, 3.1, or 3.2 incompatibility.

There is no confirmed bug due to 2.4, 2.5, 3.1, or 3.2 incompatibility.

I can't see a compelling reason for cutting support for one or more
versions before releasing the state of the art.

Günter

Dear E. Dunham,

someone interested in helping to fill the gaps in our documentation is good
news.

On 2015-04-19, E. Dunham wrote:

> Some other docs linked me into a "to be completed" section of the DTD
> guide. The instructions for what to do with "to be completed" sections
> at http://docutils.sourceforge.net/docs/ref/doctree.html#to-be-completed
> don't provide any guidance on how the authors/maintainers would like
> changes to the guide to be submitted. 

> Could you please tell me what that workflow should be (probably check
> out a copy from some link or other, write changes according to certain
> standards, email a patch to some address?), so that I can add first the
> instructions and then hopefully a bunch of the missing sections to the
> guide? 

There is no established procedure for documentation separate from code
developement. I'll try to list some points:

* Get the latest version from the repository_ (either set up a working
  copy via SVN or git or download the file(s) in question via the web
  access).
  
* Mail your patches to the `mailing list`_
  doc...@li....
  
  This is also the place for questions arising during the process.

* For the style, see the Doctutils Policies, especially the
  `documentation conventions`_ and the rest of the document (and other
  Docutils documentation) to get a feeling for tone and style. Often, you
  can copy and edit parts from other places.
  
* Start with a small edit and wait for the feedback.

.. _repository: http://docutils.sourceforge.net/docs/dev/repository.html
.. _mailing list: 
   http://docutils.sourceforge.net/docs/user/mailing-lists.html
.. _documentation conventions:
   http://docutils.sourceforge.net/docs/dev/policies.html#documentation-conventions


I hope this can get you started...

Thanks, Günter   

On Mon, Apr 20, 2015 at 3:24 PM, Jeffrey C. Jacobs
<dar...@ti...> wrote:
> Guenter Milde <milde <at> users.sf.net> writes:
>> In my view, rather than a screenplay directive, I'd create a screenplay
>> front-end that can add parts to the parser (special directives),
>> transforms (also transforms that will always run without need of having
>> them triggered by a directive), special configuration options, special
> style
>> files and maybe a special writer, too.
>>
>> For examples, you can look at rst2s5 (docutils/tools) and its components
> or
>> the html4trans writer and front end in the sandbox.
>
> I worry about using such an approach creating a multiplicity problem.
> screenplay2latex, screenplay2html, screenplay2odt, etc.  The nice thing
> about a custom directive it is makes it clear the document should be
> treated like a screenplay and thus use rst/screenplay formatting
> conventions, whatever those settle on being in the 2.0 spec (the spec
> specified on the `State of the Sphere`_ would be 1.0.
>
> .. `State of the Sphere`_ http://blog.project-
> kronosphere.timehorse.com/2009/04/1-page-1-minute.html

I recommend that you create a Screenplay Reader. From PEP 258:

"Readers understand the input context (where the data is coming from),
send the whole input or discrete "chunks" to the parser, and provide
the context to bind the chunks together back into a cohesive whole."

If you haven't read the full PEP 258 yet, do it now. You really need
the overview of Docutils' architecture for what you want to do.

Take a look at the PEP Reader, docutils/readers/pep.py, for an
example. A PEP is a type of standalone document, with a very specific
(RFC-2822) header that provides the document number and title and
other info, certain extra parsing (PEP and RFC numbers), and with a
different set of default transforms from regular standalone documents.
Your screenplays would have corresponding requirements: title page
info, a set of transforms to apply, and extra roles to make available.

As for front ends, as Günter stated, you'll have to make them anyway
in order to load your custom directive. That's just how it's done.
You'll need one for every combination of components (reader, parser,
writer). Front ends are minimal though, typically only a few
significant lines of code; they just draw in the components you need
to form your complete tool.

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

On 2015-04-20, Jeffrey C  Jacobs wrote:
> Guenter Milde <milde <at> users.sf.net> writes:
>> In my view, rather than a screenplay directive, I'd create a screenplay
>> front-end ...

> I worry about using such an approach creating a multiplicity problem.  
> screenplay2latex, screenplay2html, screenplay2odt, etc.  The nice thing 
> about a custom directive it is makes it clear the document should be 
> treated like a screenplay and thus use rst/screenplay formatting 
> conventions, 
...

But you will need a special front-end anyway, unless you plan to add a
screenplay directive to the official rST syntax.

Günter

In a message of Wed, 22 Apr 2015 01:51:48 -0500, Tony Narlock writes:
>https://github.com/sphinx-doc/sphinx/blob/1.3.1/setup.py#L44
>
>Did you encounter an issue with Sphinx?

No.  I suspect the sphinx they had is old, too.

Laura

https://github.com/sphinx-doc/sphinx/blob/1.3.1/setup.py#L44

Did you encounter an issue with Sphinx?

On Tue, Apr 21, 2015 at 8:07 AM, Laura Creighton <la...@op...> wrote:

> Datapoint.
>
> Today I went to a site to install software I wrote.  It was a CentOS system
> running Python 2.5  The docs we wrote about this software use
> docutils (and sphynx).  Getting this system upgraded beyond 2.5 is some
> huge political thing having to do with a part of the client's
> organisation I have never met.
>
> It was nice that things just dropped in and worked.
>
> Laura
>
>

Correct, the question + quotation was directed toward Günter.

On Tue, Apr 21, 2015 at 10:24 AM, David Goodger <go...@py...> wrote:

> [was: Re: [Docutils-develop] testing]
>
> On Tue, Apr 21, 2015 at 4:54 AM, Guenter Milde <mi...@us...> wrote:
> >> On Mon, Apr 20, 2015 at 10:55 AM, David Goodger <go...@py...>
> wrote:
> >
> >> What do you mean edge cases, test edges cases or version edge cases?
>
> I did not write the above, as is implied by the inclusion of my name.
> In fact, nothing that I wrote survived to the reply. This can be seen
> by counting the ">"s, but that's not always obvious. Let's try to be
> more obvious, accurate, and precise when quoting so as not to
> mis-attribute.
>
> --
> David Goodger <http://python.net/~goodger>
>
>
> ------------------------------------------------------------------------------
> BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
> Develop your own process in accordance with the BPMN 2 standard
> Learn Process modeling best practices with Bonita BPM through live
> exercises
> http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual-
> event?utm_
> source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

Project policy is to test against all versions before an official release.
Official releases (what the team releases to pypi), distributions
(packagers).

I'm removing the conflict sentence for now.

On Mon, Apr 20, 2015 at 6:53 AM, Guenter Milde <mi...@us...> wrote:

> Dear Tony,
>
> Please revert the addtion of the statement
>
>   Official releases on docutils must have tests succeed across all
>   supported python versions.
>
> to `distributing.txt`.
>
> `distributing.txt` describes how to create packages of Docutils from our
> official release packages.
>
> Packagers are not required to re-test.
> The document says: "you *can* test your package".
>
> Günter
>
>
>
> ------------------------------------------------------------------------------
> BPM Camp - Free Virtual Workshop May 6th at 10am PDT/1PM EDT
> Develop your own process in accordance with the BPMN 2 standard
> Learn Process modeling best practices with Bonita BPM through live
> exercises
> http://www.bonitasoft.com/be-part-of-it/events/bpm-camp-virtual-
> event?utm_
> source=Sourceforge_BPM_Camp_5_6_15&utm_medium=email&utm_campaign=VA_SF
> _______________________________________________
> Docutils-develop mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-develop
>
> Please use "Reply All" to reply to the list.
>

On Tue, Apr 21, 2015 at 3:08 PM, Jeffrey C. Jacobs
<dar...@ti...> wrote:
> So I'm trying to write a pending node with post-parse transformation but
> looking at the code for parts.Contents, I can't fathom where the transform
> code exits.

I assume you mean docutils.parsers.rst.directives.parts.Contents.
Please be specific, because...

> I mean, the pending node is a thin client and the run code of
> the Contents directive just creates a Pending node; it doesn't seem to do
> anything else.  I can't see the code that walks the tree to find headings
> and collect them in the Table of Contents.  What am I missing?

You should be able to figure that out from the source. Here's the line
in question:

    pending = nodes.pending(parts.Contents, rawsource=self.block_text)

What is "parts.Contents"? It is *not* the directive class,
docutils.parsers.rst.directives.parts.Contents. There's no circular
reference here. The docutils.parsers.rst.directives.parts module
doesn't know about itself by name. Modules never know about themselves
by name implicitly. Apart from built-ins, names always have to be
explicitly bound by some form of assignment (import, def, class, =,
with/as, etc.).

Search in that module for the definition of "parts" to see where it
comes from, and you'll find:

    from docutils.transforms import parts

Therefore the transform itself is here:
docutils.transforms.parts.Contents. (See? The transform is also
"parts.Contents", requiring specificity. Namespaces are one honking
great idea, but you need to understand them.)

The docstring of the docutils.nodes.pending class:

    The "pending" element is used to encapsulate a pending operation: the
    operation (transform), the point at which to apply it, and any data it
    requires.  Only the pending operation's location within the document is
    stored in the public document tree (by the "pending" object itself); the
    operation and its data are stored in the "pending" object's internal
    instance attributes.

    For example, say you want a table of contents in your reStructuredText
    document.  The easiest way to specify where to put it is from within the
    document, with a directive::

        .. contents::

    But the "contents" directive can't do its work until the entire document
    has been parsed and possibly transformed to some extent.  So the directive
    code leaves a placeholder behind that will trigger the second phase of its
    processing, something like this::

        <pending ...public attributes...> + internal attributes

    Use `document.note_pending()` so that the
    `docutils.transforms.Transformer` stage of processing can run all pending
    transforms.

In http://docutils.sourceforge.net/docs/ref/transforms.html#transforms-listed-in-priority-order
many pending transforms are listed, noted by "/p".

docutils.transforms.Transformer.apply_transforms executes all the
individual transforms, including those associated with pending nodes.
And that is called by docutils.core.Publisher.apply_transforms, which
is called from docutils.core.Publisher.publish.

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

So I'm trying to write a pending node with post-parse transformation but 
looking at the code for parts.Contents, I can't fathom where the transform 
code exits.  I mean, the pending node is a thin client and the run code of 
the Contents directive just creates a Pending node; it doesn't seem to do 
anything else.  I can't see the code that walks the tree to find headings 
and collect them in the Table of Contents.  What am I missing?

On Tue, Apr 21, 2015 at 11:13 AM, Феликс <fel...@li...> wrote:
> I asked in their GitHub, but they gave no answer.

This reminds me of the streetlight effect:

A policeman sees a drunk man searching for something under a
streetlight and asks what the drunk has lost. He says he lost his keys
and they both look under the streetlight together. After a few minutes
the policeman asks if he is sure he lost them here, and the drunk
replies, no, and that he lost them in the park. The policeman asks why
he is searching here, and the drunk replies, "this is where the light
is." -- http://en.wikipedia.org/wiki/Streetlight_effect

Sphinx is the place to ask. Perhaps try the other options in the
"Questions? Suggestions?" section on http://sphinx-dog.org .

> I looked into Sphinx code
> myself and I saw that they use RSTStateMachine class to extract information
> from document.

RST is short for reStructuredText, which is the markup language.
Docutils provides a reStructuredText parser, of which RSTStateMachine
is a part. Your problem is not with the RST parsing (which Docutils
does), but with the Python parsing that is done by Sphinx, *not* by
Docutils. Sphinx uses Docutils as a library; Sphinx inserts its own
code (that does extraction) into hooks that are called by Docutils.
Sphinx does the extraction. It seems that Sphinx is giving you
evaluated values (results) rather than the symbolic text (input). But
I do not know Sphinx at all, and I really cannot help you. Sorry.


DG


> Please, cannot you look at it once more? Our eyes are bleeding when we see
> the scary signatures that are generated by Sphinx now.
>
> P.S. Here is some copy-paste from docutils/parser/rst/states.py that is used
> in documentation generation.
>
> class RSTStateMachine(StateMachineWS):
>
>     """
>     reStructuredText's master StateMachine.
>
>     The entry point to reStructuredText parsing is the `run()` method.
>     """
>
>     def run(self, input_lines, document, input_offset=0, match_titles=True,
>             inliner=None):
>         """
>         Parse `input_lines` and modify the `document` node in place.
>
>         Extend `StateMachineWS.run()`: set up parse-global data and
>         run the StateMachine.
>         """
>         self.language = languages.get_language(
>             document.settings.language_code)
>         self.match_titles = match_titles
>         if inliner is None:
>             inliner = Inliner()
>         inliner.init_customizations(document.settings)
>         self.memo = Struct(document=document,
>                            reporter=document.reporter,
>                            language=self.language,
>                            title_styles=[],
>                            section_level=0,
>                            section_bubble_up_kludge=False,
>                            inliner=inliner)
>         self.document = document
>         self.attach_observer(document.note_source)
>         self.reporter = self.memo.reporter
>         self.node = document
>         print "DOC BEFORE"
>         print document # Here the document is only a small RST file with the
> name of the classes to parse
>         results = StateMachineWS.run(self, input_lines, input_offset,
>                                      input_source=document['source'])
>         print "DOC AFTER"
>         print document # Here the document is already fully filled with
> extracted data
>         assert results == [], 'RSTStateMachine.run() results should be
> empty!'
>         self.node = self.memo = None    # remove unneeded references
>
>
>
> 21.04.2015 18:46, David Goodger пишет:
>
> On Tue, Apr 21, 2015 at 10:26 AM, Felix-Neko <fel...@li...> wrote:
>
> Good morning!
>
> I use Sphinx-Doc to generate API documentation for my project (sphinx-
> autodoc uses StateMachineWS.run to generate document from RST with python
> class names).
>
> But alas, when I have method signatures like
>
>     def mega_method(propagation_speed=scipy.constants.c,
> order_of_matnitude=1e12)
>
> in result document it will be something like that:
>
>     mega_method(propagation_speed=299792458.0,
> order_of_magnitude=10000000000000000)
>
> Cannot you disable such constant expansion? If the signatures would be
> written just as is, it will greatly improve the readability of code
> generated!
>
> ----
> Hope on your answer,
> Felix
>
> Sorry, we cannot help you with this here. Please ask in a Sphinx forum
> or mailing list.
>
>

On Tue, Apr 21, 2015, ???????????? wrote:
> 
> I use Sphinx-Doc to generate API documentation for my project
> (sphinx-autodoc uses StateMachineWS.run to generate document from RST with
> python class names).
> 
> But alas, when I have method signatures like
> 
> *def mega_method(propagation_speed=scipy.constants.c,
> order_of_matnitude=1e12)*

This seems like a question for a Sphinx list -- AFAIK, there's nothing
related to Docutils here.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Need a book?  Use your library!

On Tue, Apr 21, 2015 at 10:26 AM, Felix-Neko <fel...@li...> wrote:
> Good morning!
>
> I use Sphinx-Doc to generate API documentation for my project (sphinx-
> autodoc uses StateMachineWS.run to generate document from RST with python
> class names).
>
> But alas, when I have method signatures like
>
>     def mega_method(propagation_speed=scipy.constants.c,
> order_of_matnitude=1e12)
>
> in result document it will be something like that:
>
>     mega_method(propagation_speed=299792458.0,
> order_of_magnitude=10000000000000000)
>
> Cannot you disable such constant expansion? If the signatures would be
> written just as is, it will greatly improve the readability of code
> generated!
>
> ----
> Hope on your answer,
> Felix

Sorry, we cannot help you with this here. Please ask in a Sphinx forum
or mailing list.

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