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.