Introduction

PHP library to parse reStructuredText documents. This library is used to generate documentation for the Doctrine project website.

Installation

You can install the Doctrine RST Parser with composer:

$ composer install doctrine/rst-parser

Usage

1<?php require 'vendor/autoload.php'; use Doctrine\RST\Configuration; use Doctrine\RST\Parser; use Doctrine\RST\HTML\Environment; use Doctrine\RST\HTML\Kernel; $configuration = new Configuration(); $environment = new Environment($configuration); $kernel = new Kernel(); $parser = new Parser($environment, $kernel, $configuration); // 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/doctrine/rst-parser>`_ '; // 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/doctrine/rst-parser">GitHub page</a></p> */
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

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:

1<?php require 'vendor/autoload.php'; use Doctrine\RST\Builder; use Doctrine\RST\Configuration; use Doctrine\RST\HTML\Kernel; $htmlKernel = new Kernel(); $configuration = new Configuration(); $builder = new Builder($htmlKernel, $configuration); $builder->build('input', 'output');
2
3
4
5
6
7
8
9
10
11
12
13

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

Configuration

Abort on error

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

1<?php $configuration->abortOnError(false);
2
3

Relative URLs

By default relative URLs are generated. If you want to disable relative URLs, use the setUseRelativeUrls() method on the Configuration object:

1<?php $configuration->setUseRelativeUrls(false);
2
3

Custom Directives

Step 1: Extends the Directive class

Write your own class that extends the Doctrine\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.

1<?php use App\RST\Directive\CautionDirective; $parser->registerDirective(new CautionDirective());
2
3
4
5

Or you can pass an array of directives when constructing your Kernel:

1<?php use App\RST\Directive\CautionDirective; $htmlKernel = new Kernel([ new CautionDirective() ]); $builder = new Builder($htmlKernel);
2
3
4
5
6
7
8
9

The CautionDirective class would look like this:

1<?php declare(strict_types=1); namespace App\RST\Directive; use Doctrine\RST\Nodes\Node; use Doctrine\RST\Nodes\WrapperNode; use Doctrine\RST\Parser; use Doctrine\RST\SubDirective; class CautionDirective extends SubDirective { public function getName() : string { return 'caution'; } /** * @param string[] $options */ public function processSub( Parser $parser, ?Node $document, string $variable, string $data, array $options ) : ?Node { return new WrapperNode($document, '<div class="caution">', '</div>'); } }
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

Now you can use the directive like this:

.. caution::

    Be careful when using this functionality!

Which would output the following HTML:

1<div class="caution"><p>Be careful when using this functionality!</p></div>

Attribution

This repository was forked from Gregwar for the Doctrine Website.

License

This library is under MIT license.