gregwar/rst

PHP library to parse reStructuredText documents

RST

PHP library to parse reStructuredText document

Usage

The parser can be used this way:

<?php

$parser = new Gregwar\RST\Parser;

// RST document
$rst = ' 
Hello world
===========

What is it?
----------
This is a **RST** document!

Where can I get it?
-------------------
You can get it on the `GitHub page <https://github.com/Gregwar/RST>`_
';

// Parse it
$document = $parser->parse($rst);

// Render it
echo $document;
/* Will output, in HTML mode:
<a id="title.1"></a><h1>Hello world</h1>
<a id="title.1.1"></a><h2>What is it?</h2>
<p>This is a <b>RST</b> document!</p>
<a id="title.1.2"></a><h2>Where can I get it?</h2>
<p>You can get it on the <a href="https://github.com/Gregwar/RST">GitHub page</a></p>
*/

For more information, you can have a look at test/document/document.rst and its result test/document/document.html

Using the builder

The builder is another tool that will parses a whole tree of documents and generates an output directory containing files.

You can simply use it with:

<?php

$builder = new Gregwar\RST\Builder;
$builder->build('input', 'output');

It will parses all the files in the input directory, starting with index.rst and scanning for dependencies references and generates you target files in the output directory. Default format is HTML.

You can use those methods on it to customize the build:

• copy($source, $destination): copy the $source file or directory to the $destination file or directory of the build
• mkdir($directory): create the $directory in build directory
• addHook($function): adds an hook that will be called after each document is parsed, this hook will be called with the $document as parameter and can then tweak it as you want
• addBeforeHook($function): adds an hook that will be called before parsing the document, the parser will be passed as a parameter

Abort on error

In some situation you want the build to continue even if there is some errors, like missing references:

<?php

// Using parser
$parser->getEnvironment()->getErrorManager()->abortOnError(false);

// Using builder
$builder->getErrorManager()->abortOnError(false);

Writing directives

Step 1: Extends the Directive class

Write your own class that extends the Gregwar\RST\Directive class, and define the method getName() that return the directive name.

You can then redefine one of the following method:

• processAction() if your directive simply tweak the document without modifying the nodes
• processNode() if your directive is adding a node
• process() if your directive is tweaking the node that just follows it

See Directive.php for more information

Step 2: Register your directive

You can register your directive by directly calling registerDirective() on your Parser object.

Else, you will have to also create your own kernel by extending the Kernel class and adding your own logic to define extra directives, see Kernel.php for more information. Then, pass the kernel when constructing the Parser or the Builder

License

This library is under MIT license

rst's Issues

please make your library composer compatible by adding composer.json

https://getcomposer.org/

Directive that just follows text

Case:

.. slide::
Test
.. image:: /img/something.png

Why not parsed?

I have this RST Code

Hello world
===========

But render is plaintext, in <p>Hello world\r\n===========\r\n</p>

I used example from README.md

$parser = new \Gregwar\RST\Parser;
$value = (string)$parser->parse($value);

Now I used the whole sample:

Hello world
===========

What is it?
----------
This is a **RST** document!

Where can I get it?
-------------------
You can get it on the `GitHub page <https://github.com/Gregwar/RST>`_

and what I see:

<p>Hello world
===========
</p>
<p>What is it?
----------
This is a <strong>RST</strong> document!
</p>
<p>Where can I get it?
-------------------
You can get it on the <a href="https://github.com/Gregwar/RST">GitHub page</a>
</p>

a link and bolder is right rendered, but heading is not correctly

fix the relativeUrl semantic

Directive example?

Thnx for RST!

I can't figure out how to write a directive. Directive code:

class Dog extends Directive
{
    public function getName()
    {
        return 'dog';
    }

    public function processNode(Parser $parser, $variable, $data, array $options)
    {
        return new Nodes\ParagraphNode('<b>'.$data.'</b>');
    }
}

Calling code:

class Thing extends Gregwar\RST\Parser {
  protected $dog;
  function __construct() {
    parent::__construct();
    $this->dog = new Dog;
    $this->registerDirective($this->dog);
  }
}

$parser = new Thing(); 
$rst = ' 
Hello world
===========

.. dog:: nothing
    :scale: 50
    :weight: 68

    This is a dog.

That was a dog.
';

// Parse it
$document = $parser->parse($rst);

// Render it
echo $document;

processNode in Dog gets the word "nothing" in the param $data. $variable is empty. $options is as expected. processNode doesn't seem to get the body (This is a dog).

What am I missing?

A tutorial would be useful. I'm willing to write one if I can figure out what's going on.

Support :doc:`Something <blha>`

Unknown Role directive should state the file and line of the unknown role

PHP Fatal error:  Uncaught exception 'Exception' with message 'Unknown directive: role' in /Users/kay/Development/rest/vendor/gregwar/rst/Gregwar/RST/ErrorManager.php:17
Stack trace:

I would expect something like:

unknown directive role in file whatever.rst on line 510

Support tables with varying colspans

Is it possible to support tables with varying colspans like this?

+-------------------+---------------+-----------------------------------------------------------------------------------------------+
| Doctrine          | PHP           | Database vendor                                                                               |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | Name                     | Version | Type                                                     |
+===================+===============+==========================+=========+==========================================================+
| **smallint**      | ``integer``   | **MySQL**                | *all*   | ``SMALLINT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_ |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **Drizzle**              | *all*   | ``INT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_      |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **PostgreSQL**           | *all*   | ``SMALLINT``                                             |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **Oracle**               | *all*   | ``NUMBER(5)``                                            |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQL Server**           | *all*   | ``SMALLINT`` ``IDENTITY`` [11]_                          |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQL Anywhere**         | *all*   | ``UNSIGNED`` [10]_ ``SMALLINT`` ``IDENTITY`` [11]_       |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQLite**               | *all*   | ``INTEGER`` [16]_                                        |
+-------------------+---------------+--------------------------+---------+----------------------------------------------------------+
| **integer**       | ``integer``   | **MySQL**                | *all*   | ``INT`` ``UNSIGNED`` [10]_ ``AUTO_INCREMENT`` [11]_      |
|                   |               +--------------------------+         |                                                          |
|                   |               | **Drizzle**              |         |                                                          |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **PostgreSQL**           | *all*   | ``INT`` [12]_                                            |
|                   |               |                          |         +----------------------------------------------------------+
|                   |               |                          |         | ``SERIAL`` [11]_                                         |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **Oracle**               | *all*   | ``NUMBER(10)``                                           |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQL Server**           | *all*   | ``INT`` ``IDENTITY`` [11]_                               |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQL Anywhere**         | *all*   | ``UNSIGNED`` [10]_ ``INT`` ``IDENTITY`` [11]_            |
|                   |               +--------------------------+---------+----------------------------------------------------------+
|                   |               | **SQLite**               | *all*   | ``INTEGER`` [16]_                                        |
+-------------------+---------------+--------------------------+---------+----------------------------------------------------------+

We are migrating from Sphinx and this is something they seem to support.

Allow more indented lists

Indented lists like:

    * A
    * B

Should be lists and not quotes

Question inline directive

Hello, could I make some inline directives ?:) something like

I write something and and I'm writting something new

I would like to get something like

I write something and <code> this is my code</code>

And I want it inline

Render table header row correctly

+-----------------------------------+---------------+-----------------------------------------------------------------------+
| Property                          | Data Type     |                                                                       |
+===================================+===============+=======================================================================+
| description                       | string        |                                                                       |
+-----------------------------------+---------------+-----------------------------------------------------------------------+
| author                            | string        |                                                                       |
+-----------------------------------+---------------+-----------------------------------------------------------------------+
| keywords                          | string        |                                                                       |
+-----------------------------------+---------------+-----------------------------------------------------------------------+

The equal signs should not appear in the html

Handle "pretty" tables

Pretty tables with + - and | should be handled

Add only directive

Administrator manual
====================

.. only:: html

    This chapter describes how to manage the extension from a superuser point of view.

.. toctree::
    :maxdepth: 5
    :titlesonly:

Add 'important' directive (and possibly other admonitions)

When I tried to parse some documentation that I had written the parser threw an exception that the important directive was unknown. Is it possible to add this?

See http://docutils.sourceforge.net/docs/ref/rst/directives.html#specific-admonitions for more information on the different admonitions

Add an errors manager

Fixes on the lists

Numbered lists can be defined with #.

Lists can contains empty lines

Can a new release be tagged?

v1.0.0 came out in 2014, is this library stable enough to declare v1.0.1?

Finish the "true" separation of what is HTML specific or not

Bug in combination of listing and code block

When I use

Installation
------------
**Stable release**
    Via the Python Package Index::

        $> pip install package

**Development version**
    For a simple system-wide installation::

        $> pip install -r requirements.txt .

    Depending on your system, you may need root privileges. On UNIX-based
    operating systems (Linux, Mac OS X etc.) this is achieved with ``sudo``.

    For development, especially if you want to test the package from within
    the source directory::

        $> pip install -r requirements.txt --user -e .

the block after the $> pip install -r requirements.txt . does not appear to be normal text but considered to be code (although it is regular text).

Failed conversion

I'm trying to parse the Godot Docs without much luck... I tried doing some hacks but it seems to made things worse... What can i do?

This is the file:

https://raw.githubusercontent.com/godotengine/godot-docs/stable/getting_started/scripting/gdscript/gdscript_basics.rst

And it parses ok in their site but they are using Sphinx:

https://docs.godotengine.org/en/stable/getting_started/scripting/gdscript/gdscript_basics.html

Two days and i'm still trying to fix links...

parser stops with missing reference

If a RST document defines a reference which cannot be found:

:ref:RST_is_not_available

the parser stops. Is it possible to just ignore these cases when using builder?

Change Form of HTML ourput

Dear Grégoire,

thanks a lot for this great peace of code. I´m unsure if this is the right place to ask if not please just close/ignore this issue.

My question is:
As far as I can see /HTML/Document renderDocument() is responsible for the html structure. Further it´s possible to inject css and js in each file. But what would be your recommend way if this HTML structure does not fit my needs? Let´s say I would like to inlude the TOC in every file or to have only the body rendered without head tag .. to include the files in other templates?

Here are my Ideas where but I´m unsure which way to go:

• there is already a setter in your code to overwrite HTML output I do not know of.
• exend f.e.: RST/Builder.php to use an extended HTML/Document.php?
• Fork and change the renderDocument() f.e. by use of external templates.

Happy about your input!

Cheers and merry christmas ;)

Toni

How to gather information why build fails?

I´m trying to use build() for conversation from rst documents to html.
Unfortunately the output dir stays empty.

error.log does not give useful information – but I found an error method.
How can I use the ->error() (or something else) to get more information what goes wrong
with build?

include_once('autoload.php');
$builder = new Gregwar\RST\Builder;
$builder->build('admin/doc/source/', 'output');
echo $builder->error;

Diacritic in table

Hello,
When Im tryin to create table with diacritic content, it fails and prints characters without diacritis.

It is possible to fix this ? Or any available solution

For example

=====  =====  ======
  Inputs     Output
------------  ------
 A      B    A or B
=====  =====  ======
Číslo  False  False
=====  =====  ======

prints:
?íslo T

Fixes on links

Links can be followed by a direct ) , or .

Wrong links for relative URLs, when starting with a forward slash

I'm facing what I believe is an issue when using links with this RST library:
When generating links that begin with '/', the resulting output does not match what I would expect as the initial forward slash gets removed from the final HTML link.

Here is an example (using RST v1.0.4):

---

Source code:

// Load RST parser.
$parser = new Parser();

// Parse input RST text.
$parsed_text = $parser->parse('
This is a link: `My link </my/path/to/link.html>`__
');
$result = $parsed_text->renderDocument();

// Output HTML result.
echo $result;

Expected result:

<p>This is a link: <a href="/my/path/to/link.html">My link</a></p>

Observed result:

<p>This is a link: <a href="my/path/to/link.html">My link</a></p>

---

Note: When using This is a link: `My link <//my/path/to/link.html>\`__ as input, it does keep one forward slash in the output, but it seems like a workaround that should not be used.

Am I missing anything here?
Best regards,
PAC

Add the figure directive

Support anchor linking

Is it possible to support something like this?

Here is some RST text. [1]_
Here is some more RST text. [2]_

.. [1] This is the note about it.
.. [2] This is another note.

The [1]_ and [2]_ turn in to links that anchor down to the list of notes below.

escape the paragraphes text for sandboxing and cleaning

Error in path

Hello, I want to parse a documentation with includes, but I only got a message, that an included file doesn't exist: .//book/map.rst.inc It looks like an bug in Environment.php (the ".//" in the path could not be correct).

Nested subdirectives broken

Thanks for the parser. A useful thing!

I defined a dude subdirective. It's similar to the div code:

namespace AppBundle\Service\RstCustomDirectives\Directives;

use Gregwar\RST\Parser;
use Gregwar\RST\SubDirective;
use Gregwar\RST\Nodes\WrapperNode;

class Dude extends SubDirective
{

    public function getName()
    {
        return 'dude';
    }

    public function processSub(Parser $parser, $document, $variable, $class, array $options)
    {
        $start = '<div';
        if ($class) {
            $start .= ' class="'.$class.'"';
        }
        $start .= '><p>DUDE!</p>';
        return new WrapperNode($document, $start, '</div>');
    }
}

Here's some test code:

        $rst = ' 
This is a **RST** document! About to div it.

.. div:: indent

    This is inside a div.

    .. div:: indent
    
        This is a nested div.
            
        .. div:: indent
    
            This is inside a nested div.

.. div:: indent

    This is a div after nested divs.

This is predude.

.. dude:: indent
    :scale: 50
    :weight: 68
    
    This is the first dude.
    
    .. dude:: indent
        :scale: 50
        :weight: 68

        This is your inner dude.

.. dude:: indent
    :scale: 50
    :weight: 68

    This is another dude.
        
This is post dude. AYE!
';
        $dudeDirective = new Dude();
        $parser = new Parser();
        $parser->registerDirective($dudeDirective);
        $document = $parser->parse($rst);
        return $this->render(':rst:rsttest.html.twig', [
            'base_dir' => realpath($this->getParameter('kernel.project_dir')).DIRECTORY_SEPARATOR,
            'parsedHtml' => $document,
        ]);

There are divs in divs, and that works. When dudes are not nested in dudes, no problem. However, when a dude is nested in a dude, like the inner dude above, the code crashes. Error:

Unknown directive: dude in (unknown) line 6

The message seems to be from $parser->getCurrentDirective(). $parser->directives[] doesn't contain dude at that point. However, dude was in $parser->directives[] earlier, when processing the first div.

Not sure this is relevant: SubDirective->process() calls $parser->getSubParser(); on line 24. That executes this line on Parser line 74:

return new Parser($this->environment, $this->kernel)

I don't see how the registered directives get passed there. Could that be the issue?

unit test the environment

Add role directive

.. ==================================================
.. DEFINE SOME TEXT ROLES
.. --------------------------------------------------

.. role::   typoscript(code)

.. role::   ts(typoscript)
   :class:  typoscript

.. role::   php(code)
    :language: php

.. highlight:: php

Embedded URIs with newlines result in incorrect anchors

Embedded URIs should allow for newlines as shown in an example at http://docutils.sourceforge.net/docs/user/rst/quickref.html#hyperlink-targets . The current parsing of links assumes the link is contained on a single line, which can result in empty anchor links. Examples:

Correct when all on one line:

INPUT 
`Google <https://google.com>`_

OUTPUT
<p><a href="https://google.com">Google</a></p>

Incorrect when spanning two lines:

INPUT 
`Google
<https://google.com>`_

OUTPUT
<p><a href="">Google
&lt;https://google.com&gt;</a></p>

Note that the Online reStructuredText Editor (http://rst.ninjs.org) correctly renders the link in both cases.

I think the fix requires Parser.php to have a new 'state' when parsing links to allow for links that span multiple lines.

support anchors # at end of references