|
1 | | -# RST |
| 1 | +# Doctrine RST Parser |
2 | 2 |
|
3 | | -[](https://travis-ci.org/Gregwar/RST) |
| 3 | +[](https://travis-ci.org/doctrine/rst-parser) |
4 | 4 |
|
5 | | -PHP library to parse reStructuredText document |
| 5 | +PHP library to parse [reStructuredText](https://en.wikipedia.org/wiki/ReStructuredText) documents. |
| 6 | +This library is used to generate documentation for the [Doctrine](https://www.doctrine-project.org) |
| 7 | +project [website](https://github.com/doctrine/doctrine-website). |
6 | 8 |
|
7 | | -## Usage |
8 | | - |
9 | | -The parser can be used this way: |
10 | | - |
11 | | -```php |
12 | | -<?php |
13 | | - |
14 | | -$parser = new Gregwar\RST\Parser; |
15 | | - |
16 | | -// RST document |
17 | | -$rst = ' |
18 | | -Hello world |
19 | | -=========== |
20 | | - |
21 | | -What is it? |
22 | | ----------- |
23 | | -This is a **RST** document! |
24 | | - |
25 | | -Where can I get it? |
26 | | -------------------- |
27 | | -You can get it on the `GitHub page <https://github.com/Gregwar/RST>`_ |
28 | | -'; |
29 | | - |
30 | | -// Parse it |
31 | | -$document = $parser->parse($rst); |
32 | | - |
33 | | -// Render it |
34 | | -echo $document; |
35 | | -/* Will output, in HTML mode: |
36 | | -<a id="title.1"></a><h1>Hello world</h1> |
37 | | -<a id="title.1.1"></a><h2>What is it?</h2> |
38 | | -<p>This is a <b>RST</b> document!</p> |
39 | | -<a id="title.1.2"></a><h2>Where can I get it?</h2> |
40 | | -<p>You can get it on the <a href="https://github.com/Gregwar/RST">GitHub page</a></p> |
41 | | -*/ |
42 | | -``` |
43 | | - |
44 | | -For more information, you can have a look at `test/document/document.rst` and its result |
45 | | -`test/document/document.html` |
46 | | - |
47 | | -## Using the builder |
48 | | - |
49 | | -The builder is another tool that will parses a whole tree of documents and generates |
50 | | -an output directory containing files. |
51 | | - |
52 | | -You can simply use it with: |
53 | | - |
54 | | -```php |
55 | | -<?php |
56 | | - |
57 | | -$builder = new Gregwar\RST\Builder; |
58 | | -$builder->build('input', 'output'); |
59 | | -``` |
60 | | - |
61 | | -It will parses all the files in the `input` directory, starting with `index.rst` and |
62 | | -scanning for dependencies references and generates you target files in the `output` |
63 | | -directory. Default format is HTML. |
64 | | - |
65 | | -You can use those methods on it to customize the build: |
66 | | - |
67 | | -* `copy($source, $destination)`: copy the `$source` file or directory to the `$destination` |
68 | | - file or directory of the build |
69 | | -* `mkdir($directory)`: create the `$directory` in build directory |
70 | | -* `addHook($function)`: adds an hook that will be called after each document is parsed, this |
71 | | - hook will be called with the `$document` as parameter and can then tweak it as you want |
72 | | -* `addBeforeHook($function)`: adds an hook that will be called before parsing the |
73 | | - document, the parser will be passed as a parameter |
74 | | - |
75 | | -## Abort on error |
76 | | - |
77 | | -In some situation you want the build to continue even if there is some errors, |
78 | | -like missing references: |
79 | | - |
80 | | -```php |
81 | | -<?php |
82 | | - |
83 | | -// Using parser |
84 | | -$parser->getEnvironment()->getErrorManager()->abortOnError(false); |
85 | | - |
86 | | -// Using builder |
87 | | -$builder->getErrorManager()->abortOnError(false); |
88 | | -``` |
89 | | - |
90 | | -## Writing directives |
91 | | - |
92 | | -### Step 1: Extends the Directive class |
93 | | - |
94 | | -Write your own class that extends the `Gregwar\RST\Directive` class, and define the |
95 | | -method `getName()` that return the directive name. |
96 | | - |
97 | | -You can then redefine one of the following method: |
98 | | - |
99 | | -* `processAction()` if your directive simply tweak the document without modifying the nodes |
100 | | -* `processNode()` if your directive is adding a node |
101 | | -* `process()` if your directive is tweaking the node that just follows it |
102 | | - |
103 | | -See `Directive.php` for more information |
104 | | - |
105 | | -### Step 2: Register your directive |
106 | | - |
107 | | -You can register your directive by directly calling `registerDirective()` on your |
108 | | -`Parser` object. |
109 | | - |
110 | | -Else, you will have to also create your own kernel by extending the `Kernel` class |
111 | | -and adding your own logic to define extra directives, see `Kernel.php` for more information. |
112 | | -Then, pass the kernel when constructing the `Parser` or the `Builder` |
113 | | - |
114 | | -## Attribution |
115 | | - |
116 | | -This repository was forked from [Gregwar\RST](https://github.com/Gregwar/RST) for the [Doctrine Website](https://github.com/doctrine/doctrine-website). |
117 | | - |
118 | | -## License |
119 | | - |
120 | | -This library is under MIT license |
| 9 | +https://www.doctrine-project.org/projects/rst-parser.html |
0 commit comments