Update website

vendor/doctrine/rst-parser/docs/en/attribution.rst

@@ -0,0 +1,5 @@
+Attribution
+===========
+
+This repository was forked from `Gregwar <https://github.com/Gregwar/RST>`_ for the `Doctrine
+Website <https://github.com/doctrine/doctrine-website>`_.

vendor/doctrine/rst-parser/docs/en/builder.rst

@@ -0,0 +1,49 @@
+Builder
+=======
+
+The ``Doctrine\RST\Builder`` class will parse a whole tree of documents
+and generate an output directory containing formatted files.
+
+It can be used like this:
+
+.. code-block:: php
+
+    use Doctrine\RST\Builder;
+
+    $builder = new Builder();
+    $builder->build('/path/to/source', '/path/to/output');
+
+It will parse all the files in the ``/path/to/source`` directory, starting with
+``index.rst``, scan for dependencies and will generate target files in the ``/path/to/output``
+directory. The Default format is HTML.
+
+Configuration
+-------------
+
+If you want to customize the builder you can pass a ``Doctrine\RST\Kernel`` instance
+with a ``Doctrine\RST\Configuration`` that allows you to customize the configuration
+used by the builder:
+
+.. code-block:: php
+
+    use Doctrine\RST\Builder;
+    use Doctrine\RST\Configuration;
+    use Doctrine\RST\Kernel;
+
+    $configuration = new Configuration();
+    $configuration->setBaseUrl('https://www.google.com');
+    $kernel = new Kernel($configuration);
+
+    $builder = new Builder($kernel);
+
+You can read more about what configuration options exist in the :ref:`Configuration <configuration>` chapter.
+
+Custom Index Name
+-----------------
+
+If your index file is not ``index.rst`` and it is something like ``introduction.rst``
+you can customize that using the ``setIndexName()`` method:
+
+.. code-block:: php
+
+    $builder->setIndexName('introduction');

vendor/doctrine/rst-parser/docs/en/configuration.rst

@@ -0,0 +1,93 @@
+Configuration
+=============
+
+Base URL
+--------
+
+Normally, all URLs are generated relative, but if you want to generate absolute URLs
+with a base url, you can use the ``baseUrl`` option:
+
+.. code-block:: php
+
+    $configuration->setBaseUrl('https://www.doctrine-project.org');
+
+Base URL Enabled Callable
+-------------------------
+
+In some cases, you may want to control when the base url gets used. For this you can set
+a callable that will be invoked when generating URLs. The callable receives a string that
+contains the path to the current file being rendered. This means you could make the parser
+only use the base url on certain paths:
+
+.. code-block:: php
+
+    // only use the base url on paths that contain the string /use-base-url/
+    $configuration->setBaseUrlEnabledCallable(static function(string $path) : bool {
+        return strpos($path, '/use-base-url/') !== false;
+    });
+
+Abort on Error
+--------------
+
+By default if an error is encountered, the parsing will be aborted. You can easily
+change this like this:
+
+.. code-block:: php
+
+    $configuration->abortOnError(false);
+
+Ignoring Invalid References
+---------------------------
+
+By default, invalid references and links will be reported as errors. If you want to
+ignore them you can do so like this:
+
+.. code-block:: php
+
+    $configuration->setIgnoreInvalidReferences(true);
+
+Format
+------
+
+By default, the Doctrine RST Parser comes with two formats, HTML and LaTeX. HTML is the default format
+and you can configure which format to use by using the following constants:
+
+- ``Doctrine\RST\Formats\Format::HTML``
+- ``Doctrine\RST\Formats\Format::LATEX``
+
+And you can configure the format to render like this:
+
+.. code-block:: php
+
+    use Doctrine\RST\Formats\Format;
+
+    $configuration->setFileExtension(Format::LATEX);
+
+You can read more about formats in the :ref:`Formats <formats>` chapter.
+
+Indent HTML
+-----------
+
+By default, the outputted HTML is not indented consistently. If you would like the outputted HTML to be
+indented consistently, you can enable this feature using the ``setIndentHTML(bool $indentHTML)`` method:
+
+.. code-block:: php
+
+    $configuration->setIndentHTML(true);
+
+.. note::
+
+    This feature only works when rendering full HTML documents using the
+    ``Doctrine\RST\Nodes\DocumentNode::renderDocument()`` method. If you render
+    an individual node with the ``render()`` method, the outputted HTML will not be indented.
+
+Initial Header Level
+--------------------
+
+Normally, document headings start at ``h1``. You can override this by setting the ``initialHeaderLevel`` configuration
+option:
+
+.. code-block:: php
+
+    // Set the top-most document header to <h2>
+    $configuration->setInitialHeaderLevel(2);

vendor/doctrine/rst-parser/docs/en/custom-directives.rst

@@ -0,0 +1,119 @@
+Custom Directives
+=================
+
+Directives are designed to be an extension mechanism for reStructuredText. It enables you to add custom
+functionality to reStructuredText without having to add new custom syntaxes.
+
+Directive Class
+---------------
+
+You can write your own directives by defining a class that extends the ``Doctrine\RST\Directives\Directive``
+class and defines the method ``getName()`` that returns the directive name.
+
+You can then implement one of the following methods:
+
+-  ``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 <https://github.com/doctrine/rst-parser/blob/HEAD/lib/Directives/Directive.php>`_ for more information.
+
+Example Directive
+-----------------
+
+.. code-block:: php
+
+    namespace App\RST\Directives;
+
+    use Doctrine\RST\Nodes\Node;
+    use Doctrine\RST\Parser;
+    use Doctrine\RST\Directives\Directive;
+
+    class ExampleDirective extends Directive
+    {
+        public function getName() : string
+        {
+            return 'example';
+        }
+
+        /**
+         * @param string[] $options
+         */
+        public function process(
+            Parser $parser,
+            ?Node $node,
+            string $variable,
+            string $data,
+            array $options
+        ) : void {
+            // do something to $node
+        }
+    }
+
+Now you can register your directive by passing it to the 2nd argument of the ``Doctrine\RST\Kernel`` class:
+
+.. code-block:: php
+
+    use App\RST\Directives\ExampleDirective;
+
+    $kernel = new Kernel($configuration, [
+        new ExampleDirective()
+    ]);
+
+    $builder = new Builder($kernel);
+
+SubDirective Class
+------------------
+
+You can also extend the ``Doctrine\RST\Directives\SubDirective`` class and implement the ``processSub()`` method if
+you want the sub block to be parsed. Here is an example ``CautionDirective``:
+
+.. code-block:: php
+
+    namespace App\RST\Directives;
+
+    use Doctrine\RST\Nodes\Node;
+    use Doctrine\RST\Nodes\WrapperNode;
+    use Doctrine\RST\Parser;
+    use Doctrine\RST\Directives\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 {
+            $divOpen = $parser->renderTemplate('div-open.html.twig', [
+                'class' => 'caution',
+            ]);
+
+            return $parser->getNodeFactory()->createWrapperNode($document, $divOpen, '</div>');
+        }
+    }
+
+Now you can use the directive like this and it can contain other reStructuredText syntaxes:
+
+.. code-block::
+
+    .. caution::
+
+        This is some **bold** text!
+
+The above example would output the following HTML:
+
+.. code-block:: html
+
+    <div class="caution"><p>This is some <strong>bold</strong> text!</p></div>

vendor/doctrine/rst-parser/docs/en/customizing-rendering.rst

@@ -0,0 +1,29 @@
+Customizing Rendering
+=====================
+
+You can customize individual templates used during the rendering process by configuring
+the ``customTemplateDirs`` option using ``setCustomTemplateDirs()`` or ``addCustomTemplateDir()``
+methods:
+
+.. code-block:: php
+
+    use Doctrine\RST\Formats\Format;
+
+    $configuration->setFileExtension(Format::HTML); // default is html
+    $configuration->setCustomTemplateDirs([
+        '/path/to/custom/templates'
+    ]);
+
+The files that you can override can be found `here <https://github.com/doctrine/rst-parser/tree/HEAD/lib/Templates/default>`_.
+
+For example, the file ``default/html/anchor.html.twig`` could be overwritten by creating the same file at
+``/path/to/custom/templates/default/html/anchor.html.twig``. All of the other templates will still use
+the core templates.
+
+If you wanted to customize the LaTeX output you can do so like this:
+
+.. code-block:: php
+
+    $configuration->setFileExtension(Format::LATEX);
+
+Now you can customize the LaTeX output by overriding files in ``/path/to/custom/templates/default/tex``.

vendor/doctrine/rst-parser/docs/en/events.rst

@@ -0,0 +1,74 @@
+Events
+======
+
+The Doctrine RST parser dispatches several different events internally which enable you
+to hook in to the core of the parser to add custom functionality.
+
+Event Manager
+-------------
+
+You can access the ``Doctrine\Common\EventManager`` instance with the ``getEventManager()`` method:
+
+.. code-block:: php
+
+    $eventManager = $configuration->getEventManager();
+
+If you want to set your own you can do so with the ``setEventManager(EventManager $eventManager)`` method:
+
+.. code-block:: php
+
+    use Doctrine\Common\EventManager;
+
+    $eventManager = new EventManager();
+
+    $configuration->setEventManager($eventManager);
+
+Listeners
+---------
+
+Add a new listener with the event manager:
+
+.. code-block:: php
+
+    use App\Listeners\PostParseDocumentListener;
+    use Doctrine\RST\Event\PostParseDocumentEvent;
+
+    $eventManager->addEventListener(
+        [PostParseDocumentEvent::POST_PARSE_DOCUMENT],
+        new PostParseDocumentListener()
+    );
+
+Now define your listener in ``App\Listeners\PostParseDocumentListener``. The ``postParseDocument()``
+method will be notified every time a document is parsed:
+
+.. code-block:: php
+
+    namespace App\Listeners;
+
+    use Doctrine\RST\Event\PostParseDocumentEvent;
+    use Doctrine\RST\Event\PostParseDocumentEvent;
+
+    class PostParseDocumentListener
+    {
+        public function postParseDocument(PostParseDocumentEvent $event)
+        {
+            $documentNode = $event->getDocumentNode();
+
+            // do something with $documentNode
+        }
+    }
+
+Available Events
+----------------
+
+The events you can listen for are as follows:
+
+- ``PreBuildScanEvent::PRE_BUILD_SCAN`` - Dispatches a method named ``preBuildScan()`` before files are scanned when using the builder.
+- ``PreBuildParseEvent::PRE_BUILD_PARSE`` - Dispatches a method named ``preBuildParse()`` before files are parsed and after they are scanned when using the builder.
+- ``PreBuildRenderEvent::PRE_BUILD_RENDER`` - Dispatches a method named ``preBuildRender()`` before files are rendered and after they are parsed when using the builder.
+- ``PostBuildRenderEvent::POST_BUILD_RENDER`` - Dispatches a method named ``postBuildRender()`` after files are rendered when using the builder.
+- ``PostNodeCreateEvent::POST_NODE_CREATE`` - Dispatches a method named ``postNodeCreate()`` after a node is created.
+- ``PreParseDocumentEvent::PRE_PARSE_DOCUMENT`` - Dispatches a method named ``preParseDocument()`` before a node is parsed.
+- ``PostParseDocumentEvent::POST_PARSE_DOCUMENT`` - Dispatches a method named ``postParseDocument()`` after a node is parsed.
+- ``PreNodeRenderEvent::PRE_NODE_RENDER`` - Dispatches a method named ``preNodeRender()`` before a node is rendered.
+- ``PostNodeRenderEvent::POST_NODE_RENDER`` - Dispatches a method named ``postNodeRender()`` after a node is rendered.

vendor/doctrine/rst-parser/docs/en/formats.rst

@@ -0,0 +1,108 @@
+Formats
+=======
+
+In addition to templates and themes, you can build formats which allow you to completely implement your
+own rendering. This library comes with two formats by default, HTML and LaTeX.
+
+To build your own format you need to implement the ``Doctrine\RST\Formats\Format`` interface:
+
+.. code-block:: php
+
+    namespace App\RST\MySpecial;
+
+    use App\MySpecial\MySpecialGenerator;
+    use Doctrine\RST\Directives\Directive;
+    use Doctrine\RST\Formats\Format;
+    use Doctrine\RST\Nodes;
+    use Doctrine\RST\Renderers\CallableNodeRendererFactory;
+    use Doctrine\RST\Renderers\NodeRendererFactory;
+
+    class MySpecialFormat implements Format
+    {
+        /** @var MySpecialGenerator */
+        private $mySpecialGenerator;
+
+        public function __construct(MySpecialGenerator $mySpecialGenerator)
+        {
+            $this->mySpecialGenerator = $mySpecialGenerator;
+        }
+
+        public function getFileExtension() : string
+        {
+            return 'myspecial';
+        }
+
+        /**
+         * @return Directive[]
+         */
+        public function getDirectives() : array
+        {
+            return [
+                // ...
+            ];
+        }
+
+        /**
+         * @return NodeRendererFactory[]
+         */
+        public function getNodeRendererFactories() : array
+        {
+            return [
+                Nodes\AnchorNode::class => new CallableNodeRendererFactory(
+                    function (Nodes\AnchorNode $node) {
+                        return new MySpecial\Renderers\AnchorNodeRenderer(
+                            $node,
+                            $this->mySpecialGenerator
+                        );
+                    }
+                ),
+
+                // implement the NodeRendererFactory interface for every node type
+            ];
+        }
+    }
+
+The ``App\RST\MySpecial\Renderers\AnchorNodeRenderer`` would look like this:
+
+.. code-block:: php
+
+    namespace App\RST\MySpecial\Renderers;
+
+    use App\MySpecial\MySpecialGenerator;
+    use Doctrine\RST\Nodes\AnchorNode;
+    use Doctrine\RST\Renderers\NodeRenderer;
+
+    class AnchorNodeRenderer implements NodeRenderer
+    {
+        /** @var AnchorNode */
+        private $anchorNode;
+
+        /** @var MySpecialGenerator */
+        private $mySpecialGenerator;
+
+        public function __construct(AnchorNode $anchorNode, MySpecialGenerator $mySpecialGenerator)
+        {
+            $this->anchorNode         = $anchorNode;
+            $this->mySpecialGenerator = $mySpecialGenerator;
+        }
+
+        public function render() : string
+        {
+            // render the node using the MySpecialGenerator instance
+        }
+    }
+
+Now add the format to the ``Configuration``:
+
+.. code-block:: php
+
+    use App\MySpecial\MySpecialGenerator;
+    use App\RST\MySpecial\MySpecialFormat;
+
+    $configuration->addFormat(new MySpecialFormat(new MySpecialGenerator()));
+
+Use the format:
+
+.. code-block:: php
+
+    $configuration->setFileExtension('myspecial');

vendor/doctrine/rst-parser/docs/en/index.rst

@@ -0,0 +1,106 @@
+Introduction
+============
+
+The Doctrine RST Parser is a PHP library that can parse `reStructuredText <https://en.wikipedia.org/wiki/ReStructuredText>`_
+documents and render them in HTML or LaTeX.
+
+Installation
+------------
+
+You can install the Doctrine RST Parser with composer:
+
+.. code-block:: console
+
+    $ composer require doctrine/rst-parser
+
+Basic Usage
+-----------
+
+Here is an example script that demonstrates how to use the RST Parser. Create a file named ``rst-test.php``
+in the root of your project and paste the following code:
+
+.. code-block:: php
+
+    require 'vendor/autoload.php';
+
+    use Doctrine\RST\Parser;
+
+    $parser = new 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/doctrine/rst-parser>`_
+    ';
+
+    // Parse it
+    $document = $parser->parse($rst);
+
+    // Render it
+    echo $document->render();
+
+Now execute the script:
+
+.. code-block:: console
+
+    $ php rst-test.php
+
+The above would output the following HTML:
+
+.. code-block:: html
+
+    <div class="section" id="hello-world">
+    <h1>Hello world</h1>
+    </div>
+    <div class="section" id="what-is-it">
+    <h2>What is it?</h2>
+    <p>This is a <strong>RST</strong> document!</p>
+    </div>
+    <div class="section" id="where-can-i-get-it">
+    <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>
+    </div>
+
+If you want to render a full HTML document you can do so with the ``renderDocument()`` method:
+
+.. code-block:: php
+
+    echo $document->renderDocument();
+
+The above would output the following:
+
+.. code-block:: html
+
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <meta charset="utf-8" />
+
+
+        </head>
+
+        <body>
+                <div class="section" id="hello-world">
+    <h1>Hello world</h1>
+    </div>
+    <div class="section" id="what-is-it">
+    <h2>What is it?</h2>
+    <p>This is a <strong>RST</strong> document!</p>
+    </div>
+    <div class="section" id="where-can-i-get-it">
+    <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>
+    </div>
+
+        </body>
+    </html>
+
+If you would like to customize the rendered HTML take a look at the :ref:`Customizing Rendering <customizing-rendering>` chapter.

vendor/doctrine/rst-parser/docs/en/sidebar.rst

@@ -0,0 +1,12 @@
+.. toctree::
+    :depth: 3
+
+    index
+    builder
+    configuration
+    customizing-rendering
+    themes
+    formats
+    events
+    custom-directives
+    attribution

vendor/doctrine/rst-parser/docs/en/themes.rst

@@ -0,0 +1,36 @@
+Themes
+======
+
+Similar to customizing individual parts of the rendering, you can have different themes that can be shared.
+
+.. code-block:: php
+
+    use Doctrine\RST\Formats\Format;
+
+    $configuration->setFileExtension(Format::HTML);
+    $configuration->setCustomTemplateDirs([
+        '/path/to/custom/templates'
+    ]);
+    $configuration->setTheme('my_theme');
+
+Now create a new directory for your theme at ``/path/to/custom/templates/my_theme/html``. Create a file
+named ``layout.html.twig`` and you can customize the layout that wraps all generated html files.
+
+.. code-block:: twig
+
+    <!DOCTYPE html>
+    <html>
+        <head>
+            <meta charset="utf-8" />
+
+            {% block head '' %}
+        </head>
+
+        <body>
+            {% block body '' %}
+        </body>
+    </html>
+
+Even with a theme, the rendering engine will continue to
+use a ``default`` directory (e.g. ``/path/to/custom/templates/default/html``
+as a fallback for any templates (see :doc:`/customizing-rendering`).