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

Re: [Docutils-users] Registering a transform that always runs, without attaching it to a custom component

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

On 2021-01-15, Clément Pit-Claudel wrote:
> On 1/15/21 6:18 AM, Guenter Milde via Docutils-users wrote:
>>> At the moment, users of the directive just call
>>> docutils.directives.register_directive('foo', FooDirective). 

>> Where is this done? A custom front-end?

> Exactly.

>>> How can I register a directive that always runs?

>>> I'm aware of the get_transform method on components, but I don't have a
>>> custom component; I'm just writing a directive.

>> I have never done this, but I'd try to get inspiration from the function
>> that processes the list returned by component.get_transform(). This is
>> transforms.Transformer.populate_from_components() where you will find::

>> So, maybe calling ::

>>   document.transformer.add_transform(FooTransform)

> This looks good, but how would I get a handle on the `document` object?

Here, you may have to re-create the working of the `publish_*()` function.
It may turn out that a custom component may be easier...
... or a post-processing step that removes not-required cache files.

Günter

Re: [Docutils-users] Registering a transform that always runs, without attaching it to a custom component

[Clément Pit-C. <cpi...@gm...>]

On 1/15/21 6:18 AM, Guenter Milde via Docutils-users wrote:
>> At the moment, users of the directive just call
>> docutils.directives.register_directive('foo', FooDirective). 
> 
> Where is this done? A custom front-end?

Exactly.

>> How can I register a directive that always runs?
> 
>> I'm aware of the get_transform method on components, but I don't have a
>> custom component; I'm just writing a directive.
> 
> I have never done this, but I'd try to get inspiration from the function
> that processes the list returned by component.get_transform(). This is
> transforms.Transformer.populate_from_components() where you will find::
> 
> So, maybe calling ::
> 
>   document.transformer.add_transform(FooTransform)

This looks good, but how would I get a handle on the `document` object?

Re: [Docutils-users] Registering a transform that always runs, without attaching it to a custom component

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

On 2021-01-14, Clément Pit-Claudel wrote:
> Hi there,

> I have a custom directive FooDirective.  It creates a custom pending
> node to run FooTransform.  FooTransform gathers all pending foo nodes
> and applies a transformation. The results are cached in a file, because
> the transformation runs costly computations.

> At the moment, users of the directive just call
> docutils.directives.register_directive('foo', FooDirective). 

Where is this done? A custom front-end?

> There's one problem: I don't have any 'foo's in the document, the cache
> should be cleared.  But, with no 'foo's, no pending node is added and
> the transform isn't executed; hence, the cache isn't cleared.

> How can I register a directive that always runs?

> I'm aware of the get_transform method on components, but I don't have a
> custom component; I'm just writing a directive.

I have never done this, but I'd try to get inspiration from the function
that processes the list returned by component.get_transform(). This is
transforms.Transformer.populate_from_components() where you will find::

        for component in components:
            if component is None:
                continue
            self.add_transforms(component.get_transforms())
            self.components[component.component_type] = component
 
So, maybe calling ::

  document.transformer.add_transform(FooTransform)
  
will do the trick (this is not tested and most probably needs adaption).



> In Sphinx I'd use app.add_transform; is there a Docutils equivalent?

> Or is there a better way to do this?

You may also consider subclassing a suitable component that adds the
transform. This can be done in the same module/script that also registers
the directive.

Günter

[Docutils-users] RTL languages in reStructredText (docutils)

[Abdullah Al-h. <al...@ho...>]

Hi ,

I have translated docutils to Arabic, and it is working fine, however, I am getting the direction wrong ( text is aligned to left)
[cid:image003.jpg@01D6EB29.AA4121B0]

I saw these two scripts on Docutils FAQ (Frequently Asked Questions) (sourceforge.io)<https://docutils.sourceforge.io/FAQ.html#can-i-produce-documents-in-right-to-left-languages> , which should solve this issue.

I followed the instruction but when I run rst2html_bidi  I get the following error

AttributeError: 'Element' object has no attribute 'dir'
Exiting due to error.  Use "--traceback" to diagnose.
Please report errors to <doc...@li...>.
Include "--traceback" output, Docutils version (0.17b.dev [release]),
Python version (3.7.9), your OS type & version, and the
command line used.


Traceback (most recent call last):
  File "./rst2html_hibidi.py", line 38, in <module>
    publish_cmdline(writer=HiBiDiWriter(), description=description)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 355, in publish_cmdline
    config_section=config_section, enable_exit_status=enable_exit_status)
  File "/home/geohadab/github/docutils/docutils/docutils/core.py", line 220, in publish
    output = self.writer.write(self.document, self.destination)
  File "/home/geohadab/github/docutils/docutils/docutils/writers/__init__.py", line 79, in write
    self.translate()
  File "./rst2html_hibidi.py", line 30, in translate
    self.output = hibidi.hibidi_unicode(self.output, encoding=self.destination.encoding)
  File "/home/geohadab/github/hibidi.py", line 34, in hibidi_unicode
    return hibidi_str(u.encode(encoding), root).decode(encoding)
  File "/home/geohadab/github/hibidi.py", line 39, in hibidi_str
    hibidi_dom(doc, root)
  File "/home/geohadab/github/hibidi.py", line 50, in hibidi_dom
    assign_dirs(node)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 101, in assign_dirs
    assign_dirs(child, node.dir)
  File "/home/geohadab/github/hibidi.py", line 97, in assign_dirs
    if not node.dir:
AttributeError: 'Element' object has no attribute 'dir'


Could you please help


Thank you

[Docutils-users] Registering a transform that always runs, without attaching it to a custom component

[Clément Pit-C. <cpi...@gm...>]

Hi there,

I have a custom directive FooDirective.  It creates a custom pending node to run FooTransform.  FooTransform gathers all pending foo nodes and applies a transformation.
The results are cached in a file, because the transformation runs costly computations.

At the moment, users of the directive just call docutils.directives.register_directive('foo', FooDirective).  There's one problem: I don't have any 'foo's in the document, the cache should be cleared.  But, with no 'foo's, no pending node is added and the transform isn't executed; hence, the cache isn't cleared.

How can I register a directive that always runs? I'm aware of the get_transform method on components, but I don't have a custom component; I'm just writing a directive.

In Sphinx I'd use app.add_transform; is there a Docutils equivalent?
Or is there a better way to do this?

Thanks!

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

On 2020-12-07, Gökçe Aydos wrote:

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

> On 07/12/2020 18:07, Alan G. Isaac wrote:
>> The include directive allows literal inclusion of fragments:

> Very good idea if I have a single file where I get my code blocks.

> I have many code snippets which are build on top of each other, or are 
> independent.

> I could put all the code fragments in a single file and address them 
> using the include directive. Then I would have to find a way to 
> synchronize the two views. I find this still inconvenient compared to a 
> single file solution.

> Does someone have a better solution?

* PyLit__, the bidirectional text/code converter.

* An editor with support for rectangular regions and/or (un)indenting.

* Markdown (with Docutils version 0.17b.dev).

Günter

__ https://pypi.org/project/pylit/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 07/12/2020 18:07, Alan G. Isaac wrote:
> The include directive allows literal inclusion of fragments:

Very good idea if I have a single file where I get my code blocks.

I have many code snippets which are build on top of each other, or are 
independent.

I could put all the code fragments in a single file and address them 
using the include directive. Then I would have to find a way to 
synchronize the two views. I find this still inconvenient compared to a 
single file solution.

Does someone have a better solution?

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

The include directive allows literal inclusion of fragments:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#including-an-external-document-fragment

hth, Alan Isaac


On 12/6/2020 3:01 PM, Gökçe Aydos wrote:
> Thanks, that is a good idea for longer code Alan!
> 
> My case is different. For example in one document I have about 50 code blocks, which are about 2 to 8 lines long. Creating 50 files for this purpose would be 
> very inconvenient.


 > On 06/12/2020 20:34, Alan G. Isaac wrote:
 >> Why copy/paste at all when you can just ``include`` code?
 >

Re: [Docutils-users] alternative heading syntax

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

On 2020-12-03, Danil Shkodin wrote:

> Hello.

> Do you mind telling please if there is a way to alternate the way headings
> are marked up?

Actually, reStructuredText does not include a markup alternative for
"one-line section headings" and there is no plan to indroduce them.

The development version 0.17b.dev in the repository has experimental
support for Markdown sources, where they are part of the format
specification.

> My biggest issues with the current style are that
> It is uncomfortable to text search for all heading lines since the syntax
> makes them at least 2 lines
> and I have to change the size of underline when I change the text.

Some text editors__ will help you with this task.
I use the "JED programmers editor" with rst mode and Search>List_Routines
presents me with an "Outline" window showing the document structure as well as
functions to go to the next or previous section heading.


__ https://docutils.sourceforge.io/docs/user/links.html#editors

> Would be nice if I could just use some substitution or a directive or a
> role.
> But I do not seem to find anything sufficient in the documentation.
> And I do not want to modify or extend docutils.

> Apart from that the specification suits my ideas of beauty and simplicity.

You may also consider writing your own function to recognize headings,
something along::

   % Check whether the point is in a line underlining a section title.
   % (underline is equal or longer than previous line and previous line is
   % no adornment line and non-blank).
   % Leave point at bol of underline.
   define is_heading_underline()
   {
      !if (up(1)) % already on first line 
         return 0;
      % Get length of heading
      variable heading_len = get_line_len();
      if (not(re_looking_at(".*[a-zA-Z0-9]")))
          heading_len = 0;
      go_down_1();
      !if (heading_len) % blank line, no heading
         return 0;
      % Compare to length of adornment
      return get_line_len() >= heading_len;
   }  

(This is the S-Lang__ code used in the "jed" editor).

__ http://www.jedsoft.org/slang/

Günter

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

On 2020-12-05, Gökçe Aydos wrote:

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

> I use rst heavily for my documents and slides for teaching which in turn 
> include many code blocks. Is it possible to use code blocks in rst 
> without indenting them, e.g., like *fenced code blocks*?

> The reason is, it is cumbersome to copy and paste indented code blocks. 
> There is an extension for Sphinx for this purpose [1]. Is there a plan 
> to integrate fenced code blocks in rst?

There are currently no plans to do that and I do not expect this to come
easily or anytime soon. (You many, however, file (or add to) an enhancment
ticket at the issue tracker 
https://sourceforge.net/p/docutils/feature-requests/.)

One problem with [1] is a possible clash with section underlining like ::

  Tip
  ```
  
  In rST, section underlines may use any of the characters
  ``= - ` : ' " ~ ^ _ * + # < >``.
  
The development version 0.17b.dev in the repository has experimental support
for Markdown sources, where fenced literal blocks are part of the
format specification.

Günter


> [1] https://sphinx-codefence.readthedocs.io/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

On 2020-12-06, Gökçe Aydos wrote:

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

> On 06/12/2020 20:34, Alan G. Isaac wrote:
>> Why copy/paste at all when you can just ``include`` code?

> Thanks, that is a good idea for longer code Alan!

> My case is different. For example in one document I have about 50 code 
> blocks, which are about 2 to 8 lines long. Creating 50 files for this 
> purpose would be very inconvenient.


> When I copy code from the rendered version then it's no problem, but 
> copying from the rst source is very error-prone due to the indentation, 
> e.g.,:

> code:: sh

>    cat > file <<EOF
>      4spaces here instead of 2
>    and EOF does not work
>    EOF

When working with reStructuredText, I find myself using the "rectangualar
blocks" feature of my text editor a lot.

However, your example looks a lot like a use case for `PyLit`_, where you
can convert easily in both directions between a "text" and "code" version
of a document, e.g.,

text::

  # Options for HTML output
  # -----------------------
  #
  # The style sheet to use for HTML and HTML Help pages. A file of that name
  # must exist either in Sphinx' static/ path, or in one of the custom paths
  # given in html_static_path::
  
  html_style = 'pylit-sphinx.css'
  # html_style = 'sphinxdoc.css'
  
  # Options to the theme, like a sidebar that is visible even when
  # scrolling (TODO: how to get this to work (maybe just update Spinx)?)::
  
  #html_theme_options = {'stickysidebar': 'true'}
  
  # The name for this set of Sphinx documents.  If None, it defaults to
  # "<project> v<release> documentation". ::
  
  html_title = "PyLit"
  
  # A shorter title for the navigation bar.  Default is the same as html_title.
  # ::
  
  html_short_title = "Home"

code::
  
  Options for HTML output
  -----------------------
  
  The style sheet to use for HTML and HTML Help pages. A file of that name
  must exist either in Sphinx' static/ path, or in one of the custom paths
  given in html_static_path::
  
    html_style = 'pylit-sphinx.css'
    # html_style = 'sphinxdoc.css'
    
  Options to the theme, like a sidebar that is visible even when
  scrolling (TODO: how to get this to work (maybe just update Spinx)?)::
  
    #html_theme_options = {'stickysidebar': 'true'}
    
  The name for this set of Sphinx documents.  If None, it defaults to
  "<project> v<release> documentation". ::
  
    html_title = "PyLit"
    
  A shorter title for the navigation bar.  Default is the same as html_title.
  ::
  
    html_short_title = "Home"


Günter


.. _Pylit: https://pypi.org/project/pylit/

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

El dom, 6 dic 2020 a las 17:02, Gökçe Aydos (<goe...@th...>)
escribió:


> My case is different. For example in one document I have about 50 code
> blocks, which are about 2 to 8 lines long. Creating 50 files for this
> purpose would be very inconvenient.
>

You don't need to do that. The include directive accepts the "start-line"
and "end-line" parameters which allow you to take information from a
separate file. Also, if you edit the file frequently, you can add delimiter
comments to the sections of code and use the :start-after: and :end-before:
parameters.

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

On 06/12/2020 20:34, Alan G. Isaac wrote:
> Why copy/paste at all when you can just ``include`` code?

Thanks, that is a good idea for longer code Alan!

My case is different. For example in one document I have about 50 code 
blocks, which are about 2 to 8 lines long. Creating 50 files for this 
purpose would be very inconvenient.

When I copy code from the rendered version then it's no problem, but 
copying from the rst source is very error-prone due to the indentation, 
e.g.,:

code:: sh

   cat > file <<EOF
     4spaces here instead of 2
   and EOF does not work
   EOF

Re: [Docutils-users] Is there a plan to integrate fenced code blocks in rst?

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

Why copy/paste at all when you can just ``include`` code?
Alan Isaac (who is just another user)


On 12/5/2020 5:15 AM, Gökçe Aydos wrote:
> I use rst heavily for my documents and slides for teaching which in turn include many code blocks. Is it possible to use code blocks in rst without indenting 
> them, e.g., like *fenced code blocks*?
> 
> The reason is, it is cumbersome to copy and paste indented code blocks. There is an extension for Sphinx for this purpose [1]. Is there a plan to integrate 
> fenced code blocks in rst?

Re: [Docutils-users] RST margin right question

[engelbert g. <eng...@gm...>]

On Sun, 6 Dec 2020 at 07:30, John Yara <len...@gm...> wrote:

> Hi
>
> I did a lot of research but i did not find anything useful.
> I have an issue when i write in a file.rst something like that.
>
> ::
>
>    Paragraph 1
>
>
> When i convert it into pdf with rst2pdf we can see that the paragraph have
> margin left and right around 2cm.
> I would like to know if it's possible to change the margin-right to have
> only 1cm. ?
>
> Sorry for my english.
>

thanks for the question.

margins are not part of "text" but the "view", "indentation" is "markup" in
rST (and python)
the view depends on styleshhets in html, sty-les in latex
assuming you use rst2pdf from pypi there are stylesheets too
see https://rst2pdf.org/static/manual.pdf

all the best

> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>

[Docutils-users] Is there a plan to integrate fenced code blocks in rst?

[Gökçe A. <goe...@th...>]

I use rst heavily for my documents and slides for teaching which in turn 
include many code blocks. Is it possible to use code blocks in rst 
without indenting them, e.g., like *fenced code blocks*?

The reason is, it is cumbersome to copy and paste indented code blocks. 
There is an extension for Sphinx for this purpose [1]. Is there a plan 
to integrate fenced code blocks in rst?

I am not subscribed and would be happy if you could CC me.

[1] https://sphinx-codefence.readthedocs.io/

[Docutils-users] alternative heading syntax

[Danil S. <shk...@gm...>]

Hello.

Do you mind telling please if there is a way to alternate the way headings
are marked up?

My biggest issues with the current style are that
It is uncomfortable to text search for all heading lines since the syntax
makes them at least 2 lines
and I have to change the size of underline when I change the text.

Would be nice if I could just use some substitution or a directive or a
role.
But I do not seem to find anything sufficient in the documentation.
And I do not want to modify or extend docutils.

Apart from that the specification suits my ideas of beauty and simplicity.

Thank you.

Someone's older discussion.
https://sourceforge.net/p/docutils/mailman/message/30356904/

[Docutils-users] RST margin right question

[John Y. <len...@gm...>]

Hi

I did a lot of research but i did not find anything useful.
I have an issue when i write in a file.rst something like that.

::

   Paragraph 1


When i convert it into pdf with rst2pdf we can see that the paragraph have
margin left and right around 2cm.
I would like to know if it's possible to change the margin-right to have
only 1cm. ?

Sorry for my english.

Re: [Docutils-users] Additional List of TOC generated when publishing from doctree

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

On 2020-11-30, Thomas Krug via Docutils-users wrote:

> Hi there,

> I'm using docutils to generate latex which works great.
> But I stumbled upon a problem with TOC generation.

> If I use publish_string() the generated tex is correct.
> If I use publish_doctree() then publish_from_doctree() the generated tex
> contains an additional list containing the TOC.

Thank you for the report and example. This was actually a bug in the latex
writer - not ignoring the Docutils-generated ToC with use-latex-toc.

(The "Contents" transform skips the generation when the "use-latex-toc"
setting is True, but this setting is unknown when generating the doctree
with publish_doctree().)

This is now fixed in the repository (r8582).

Thanks again
Günter

[Docutils-users] Additional List of TOC generated when publishing from doctree

[Thomas K. <t....@tu...>]

Hi there,

I'm using docutils to generate latex which works great.
But I stumbled upon a problem with TOC generation.

If I use publish_string() the generated tex is correct.
If I use publish_doctree() then publish_from_doctree() the generated tex
contains an additional list containing the TOC.

I'm not sure if I'm missing something here.

I attached a minimal working example and the diff of the generated tex
files.

Greetings,
Thomas

[Docutils-users] Docutils Markdown parser (was: Is reStructuredText required for conversion to HTML)

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

Dear Cris, Omer, and everybody,

On 2020-09-23, chris sewell wrote:
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users
> <doc...@li...> wrote:
> > On 2020-09-23, Omer Shommo wrote:

> > > I am new to docutils. I need to know if Docutils need source files
> > > to be in reStructuredText format before converting them to HTML,
> > > LaTeX, man-pages, open-document or XML.

> > Yes, currently reStructuredText ist the only input format for Docutils.

> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx,
> but the base renderer is purely docutils. It also underpins
> https://myst-nb.readthedocs.io<https://myst-nb.readthedocs.io/en/latest/>
> and http://jupyterbook.org, to render Jupyter notebooks to docutils AST

Thank you for the link. When trying to install the myst-parser via pip3,
I unfortunately got a lot of unwanted requirements (one more Docutils and
Sphinx installation + several helpers).

The following proof-of-concept of a Markdown to HTML front-end therefore
relies on recommonmark::

  #!/usr/bin/env python
  # -*- coding: utf8 -*-
  # :Copyright: © 2020 Günter Milde.
  # :License: Released under the terms of the `2-Clause BSD license`_
  #
  # .. _2-Clause BSD license: https://opensource.org/licenses/BSD-2-Clause
  """
  A minimal front end to the Docutils Publisher, parsing CommonMark markdown files
  with `recommonmark` and producing HTML 5 documents.
  
  The output is also valid XML.
  """
  from docutils.core import publish_cmdline, default_description
  
  from recommonmark.parser import CommonMarkParser
  
  mdparser = CommonMarkParser()
  
  description = (u'Generate HTML5 documents from standalone '
                 u'MarkDown (CommonMark) sources.\n'
                 + default_description)
  
  publish_cmdline(parser=mdparser, writer_name='html5',
                  description=description)

This allows to convert your standalonde README.md document into HTML, say.

Similar front-ends would be easy to construct replacing the
recommonmark.parser with the myst-parser or the writer name with the name of
other standard Docutils writers.

A better integration would include a "rmd" parser module that integrates the
configurion of the markdown parser into the standard Docutils configuration
framework.
https://docutils.sourceforge.io/docs/user/config.html




Thanks,
Günter

--

A: It reverses the normal flow of conversation.
Q: What's wrong with top-posting?
A: Top-posting.
Q: What's the biggest scourge on plain text email discussions?

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

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

On 2020-09-24, Chris Sewell wrote:

> Indeed, the Docutils maintainers may be able to offer a better
> explanation, but IMO there are a few distinct aspects of Docutils to
> bare in mind:

> - The Docutils Abstract Syntax Tree (AST, aka doctree): this is the
>   structure that holds the document in an input/output agnostic format.
>   It has (in principal) nothing to do with the input format
>   reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc

The specification https://www.python.org/dev/peps/pep-0258/#document-tree
describes the `Document Tree` as a data structure is similar to a DOM tree,
but with specific node names (classes) instead of DOM's generic nodes.
The schema is documented in an XML DTD (eXtensible Markup Language
Document Type Definition) docutils.dtd__

__ http://docutils.sourceforge.net/docs/ref/docutils.dtd

> - The input parser, which converts a (text) file to the AST, of which
>   is the reStructuredText parser is the primary example. MyST does the
>   same for Markdown, and also “shares" reStructuredText’s
>   role/directive syntax extension system

Actually, the `parser` parses an input string presented to it by the
`reader` (it may come from file or other sources).

> - The output renderer, which converts the AST to the output format

In Docutils, this component is called a `writer`.

> What sphinx does is, in essence, extend the Docutils render process to
> better deal with multiple, inter-connected, documents (e.g.  a full
> website/book). For example, adding cross-document referencing and AST
> caching.

Spinx also provides a framework for several extensions, including 
at least two Markdown parsers (recommonmark and myst-parser).

These parsers should in principle also work with core Docutils. However,
I don't know of any implementation or documentation for this combination.

It would be a nice advancement, to have frontends similar to rst2...
that work with markdown input.

Another idea would be to add a ``:format:`` option to the "include"
directive that allows things like::

  .. include:: README.md
     :format: markdown
     
This could be an optional feature depending on an external markdown
parser that can be imported from Docutils. (Somewhat similar to
syntax-highlight with Pygments or some HTML-Math-Output options.)


Yet another idea is a Docutils-XML parser that would parse the native
Docutils XML format - allowing to store parsed documents as XML and
offers a gateway to the XML world (e.g. converting any input to Docutils
XML via XSLT).


Günter

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Chris S. <chr...@ho...>]

Indeed, the Docutils maintainers may be able to offer a better explanation, but IMO there are a few distinct aspects of Docutils to bare in mind:

- The Docutils Abstract Syntax Tree (AST, aka doctree): this is the structure that holds the document in an input/output agnostic format.
   It has (in principal) nothing to do with the input format reStructuredText/Markdown/etc, or the output format HTML/LaTeX/etc
-  The input parser, which converts a (text) file to the AST, of which is the reStructuredText parser is the primary example.
    MyST does the same for Markdown, and also “shares" reStructuredText’s  role/directive syntax extension system
- The output renderer, which converts the AST to the output format

What sphinx does is, in essence, extend the Docutils render process to better deal with multiple, inter-connected, documents (e.g.  a full website/book). For example, adding cross-document referencing and AST caching.

> On 24 Sep 2020, at 01:29, Marc Rintsch <ma...@ri...> wrote:
> 
> On 23.09.20 23:31, Omer Shommo wrote:
>> […] So, is it safe to say that SPHINX uses DOCUTILS to convert plain text files into reStructuredText (.rst) files?
> 
> No, not at all.  Docutils converts reStructuredText into different output formats like HTML and LaTeX (which in turn can be converted to PDF).  Sphinx extends Docutils by some roles and directives and generates things like index pages.
> 
> Sphinx/Docutils doesn't convert *into* reStructuredText but *from* reStructuredText.
> 
> Ciao,
> 	Marc 'BlackJack' Rintsch
> -- 
> “A designer knows he has achieved perfection not when there is
> nothing left to add, but when there is nothing left to take away.”
>  -- Antoine de Saint-Exupéry
> 
> 
> _______________________________________________
> 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] Docutils-users Digest, Vol 143, Issue 1

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

On 23.09.20 23:31, Omer Shommo wrote:
> […] So, is it safe to say that SPHINX uses DOCUTILS to convert 
> plain text files into reStructuredText (.rst) files?

No, not at all.  Docutils converts reStructuredText into different 
output formats like HTML and LaTeX (which in turn can be converted to 
PDF).  Sphinx extends Docutils by some roles and directives and 
generates things like index pages.

Sphinx/Docutils doesn't convert *into* reStructuredText but *from* 
reStructuredText.

Ciao,
	Marc 'BlackJack' Rintsch
-- 
“A designer knows he has achieved perfection not when there is
  nothing left to add, but when there is nothing left to take away.”
   -- Antoine de Saint-Exupéry

Re: [Docutils-users] Docutils-users Digest, Vol 143, Issue 1

[Omer S. <os...@gm...>]

Thanks Chris. So, is it safe to say that SPHINX uses DOCUTILS to convert
plain text files into reStructuredText (.rst) files?

Thanks

On Wed, Sep 23, 2020 at 7:06 AM <
doc...@li...> wrote:

> Send Docutils-users mailing list submissions to
>         doc...@li...
>
> To subscribe or unsubscribe via the World Wide Web, visit
>         https://lists.sourceforge.net/lists/listinfo/docutils-users
> or, via email, send a message with subject or body 'help' to
>         doc...@li...
>
> You can reach the person managing the list at
>         doc...@li...
>
> When replying, please edit your Subject line so it is more specific
> than "Re: Contents of Docutils-users digest..."
> Today's Topics:
>
>    1. Is reStructuredText required for conversion to HTML (Omer Shommo)
>    2. Re: Is reStructuredText required for conversion to HTML
>       (Guenter Milde)
>    3. Re: Is reStructuredText required for conversion to HTML
>       (chris sewell)
>
>
>
> ---------- Forwarded message ----------
> From: Omer Shommo <os...@gm...>
> To: docutils-users <doc...@li...>
> Cc:
> Bcc:
> Date: Tue, 22 Sep 2020 22:02:05 -0500
> Subject: [Docutils-users] Is reStructuredText required for conversion to
> HTML
> Hello Everybody,
>
> I am new to docutils. I need to know if Docutils need source files to be
> in reStructuredText format before converting them to HTML, LaTeX,
> man-pages, open-document or XML
>
> Thanks
>
>
>
> ---------- Forwarded message ----------
> From: Guenter Milde <mi...@us...>
> To: doc...@li...
> Cc:
> Bcc:
> Date: Wed, 23 Sep 2020 06:36:18 -0000 (UTC)
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> On 2020-09-23, Omer Shommo wrote:
>
> > Hello Everybody,
>
> > I am new to docutils. I need to know if Docutils need source files to be
> in
> > reStructuredText format before converting them to HTML, LaTeX, man-pages,
> > open-document or XML
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
>
>
>
> ---------- Forwarded message ----------
> From: chris sewell <chr...@ho...>
> To: Guenter Milde <mi...@us...>
> Cc: "doc...@li..." <
> doc...@li...>
> Bcc:
> Date: Wed, 23 Sep 2020 06:54:35 +0000
> Subject: Re: [Docutils-users] Is reStructuredText required for conversion
> to HTML
> Well actually myst-parser is a Markdown to docutils AST renderer
> https://myst-parser.readthedocs.io, it is generally used via sphinx, but
> the base renderer is purely docutils.
> It also underpins https://myst-nb.readthedocs.io
> <https://myst-nb.readthedocs.io/en/latest/> and http://jupyterbook.org,
> to render Jupyter notebooks to docutils AST
>
> Kind Regards,
> Chris
>
> On 23 Sep 2020, at 07:37, Guenter Milde via Docutils-users <
> doc...@li...> wrote:
>
> On 2020-09-23, Omer Shommo wrote:
>
> Hello Everybody,
>
>
> I am new to docutils. I need to know if Docutils need source files to be in
>
> reStructuredText format before converting them to HTML, LaTeX, man-pages,
>
> open-document or XML
>
>
> Yes, currently reStructuredText_ ist the only input format for Docutils.
>
> Günter
>
>
> .. _reStructuredText:
> https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html
>
>
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>
> Please use "Reply All" to reply to the list.
>
> _______________________________________________
> Docutils-users mailing list
> Doc...@li...
> https://lists.sourceforge.net/lists/listinfo/docutils-users
>