[FEATURE] Convert basic mark-down into restructured Text

* headlines
* paragpraphs
* links
* lists

packages/guides-theme-rst/resources/config/guides-theme-rst.php

@@ -121,6 +121,7 @@
 use phpDocumentor\Guides\RestructuredText\Toc\GlobSearcher;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
 use phpDocumentor\Guides\RstTheme\Renderer\RstRenderer;
+use phpDocumentor\Guides\RstTheme\Twig\RstExtension;
 use phpDocumentor\Guides\Settings\SettingsManager;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
@@ -151,5 +152,11 @@
                 'format' => 'rst',
             ],
         )
-;
+
+        ->set(RstExtension::class)
+        ->arg('$nodeRenderer', service('phpdoc.guides.output_node_renderer'))
+        ->tag('twig.extension')
+        ->autowire()
+
+    ;
 };

packages/guides-theme-rst/resources/template/rst/body/code.rst.twig

@@ -1,4 +1,3 @@
-\lstset{language={{ node.language }}{{ '}'}}
-\begin{lstlisting}
+```
 {{ node.value|raw }}
-\end{lstlisting}
+```

packages/guides-theme-rst/resources/template/rst/body/list/list.rst.twig

@@ -1,12 +1,9 @@
-{% set keyword = 'itemize' %}
-
-{% if node.isOrdered %}
-    {% set enumerate = 'ol' %}
-{% endif %}
-
-
-\begin{{ '{' }}{{ keyword }}{{ '}' }}
-    {% for item in node.items %}
-        {{ renderNode(item) }}
-    {% endfor %}
-\end{{ '{' }}{{ keyword }}{{ '}' }}
+{% if node.isOrdered -%}
+    {%- for item in node.value -%}
+        #.  {{ renderNode(item.value)|raw }}{{ "\n\n" }}
+    {% endfor -%}
+{%- else -%}
+    {%- for item in node.value -%}
+        *   {{ renderNode(item.value)|raw }}{{ "\n" }}
+    {%- endfor -%}
+{%- endif -%}

packages/guides-theme-rst/resources/template/rst/body/paragraph.rst.twig

@@ -1,5 +1,4 @@
-{%- set text = renderNode(node.value) -%}
-
+{%- set text = renderNode(node.value)|raw -%}
 {%- if text|trim %}
     {{- text|raw -}}
 {% endif -%}

packages/guides-theme-rst/resources/template/rst/body/quote.rst.twig

@@ -1,3 +1 @@
-\begin{quotation}
-{{ renderNode(node.value) }}
-\end{quotation}
+    {{ renderNode(node.value) }}

packages/guides-theme-rst/resources/template/rst/body/separator.rst.twig

@@ -1 +1 @@
-\ \
+====

packages/guides-theme-rst/resources/template/rst/inline/image.rst.twig

@@ -0,0 +1,2 @@
+..  figure:: {{ node.url }}
+    :alt: {{ node.altText }}

packages/guides-theme-rst/resources/template/rst/inline/link.rst.twig

@@ -0,0 +1,7 @@
+{%- if node.url -%}
+    `{{ node.value|raw }} <{{- node.url -}}>`__
+{%- elseif node.targetReference -%}
+    :doc:`{{ node.value|raw }} <{{- node.targetReference -}}>`
+{%- else -%}
+    {{- node.value -}}
+{%- endif -%}

packages/guides-theme-rst/resources/template/rst/inline/literal.rst.twig

@@ -1 +1 @@
-\texttt{{ '{' }}{{- node.value -}}{{ '}' }}
+`{{- node.value -}}`

packages/guides-theme-rst/resources/template/rst/inline/plain-text.rst.twig

@@ -1 +1 @@
-{{- node.value -}}
+{{- node.value|raw -}}

packages/guides-theme-rst/resources/template/rst/structure/document.rst.twig

@@ -1,3 +1,3 @@
-{% for child in node.children %}
-    {{ renderNode(child) }}
-{% endfor %}
+{% for child in node.children -%}
+    {{- renderNode(child) -}}
+{%- endfor %}

packages/guides-theme-rst/resources/template/rst/structure/header-title.rst.twig

@@ -1,13 +1 @@
-{%- set headingLevel = node.level -%}
-{% if headingLevel == 1 %}
-===
-{{ renderNode(node.value)) }}
-===
-{% elseif headingLevel == 2 %}
-{% elseif headingLevel == 3 %}
-{% elseif headingLevel == 4 %}
-{% elseif headingLevel == 5 %}
-{% elseif headingLevel == 6 %}
-{{- renderNode(node.value) -}}
-{% endif %}
-
+{{ renderRstTitle(node, renderNode(node.value)) }}

packages/guides-theme-rst/resources/template/rst/structure/project.rst.twig

@@ -1,4 +1,3 @@
-
-{%- for document in documents -%}
-{{ renderNode(document) }}
+{%- for document in documents %}
+    {{- renderNode(document) }}
 {%- endfor -%}

packages/guides-theme-rst/resources/template/rst/structure/section.rst.twig

@@ -1,3 +1,4 @@
-{% for childNode in node.children %}
-    {{ renderNode(childNode) }}
-{% endfor %}
+{% for childNode in node.children -%}
+    {{- renderNode(childNode) }}
+
+{% endfor -%}

packages/guides-theme-rst/src/RstTheme/Configuration/HeaderSyntax.php

@@ -0,0 +1,32 @@
+<?php
+
+namespace phpDocumentor\Guides\RstTheme\Configuration;
+
+enum HeaderSyntax: int
+{
+    case H1 = 1;
+    case H2 = 2;
+    case H3 = 3;
+    case H4 = 4;
+    case H5 = 5;
+    case H6 = 6;
+    public function delimiter(): string
+    {
+        return match($this)
+        {
+            HeaderSyntax::H1, HeaderSyntax::H2 => '=',
+            HeaderSyntax::H3 => '-',
+            HeaderSyntax::H4 => '~',
+            HeaderSyntax::H5 => '#',
+            HeaderSyntax::H6 => '*',
+        };
+    }
+    public function hasTopDelimiter(): bool
+    {
+        return match($this)
+        {
+            HeaderSyntax::H1 => true,
+            default => false,
+        };
+    }
+}

packages/guides-theme-rst/src/RstTheme/Twig/RstExtension.php

@@ -0,0 +1,69 @@
+<?php
+
+declare(strict_types=1);
+
+/**
+ * This file is part of phpDocumentor.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ *
+ * @link https://phpdoc.org
+ */
+
+namespace phpDocumentor\Guides\RstTheme\Twig;
+
+use League\Flysystem\Exception;
+use League\Uri\Uri;
+use League\Uri\UriInfo;
+use LogicException;
+use phpDocumentor\Guides\Meta\InternalTarget;
+use phpDocumentor\Guides\Meta\Target;
+use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\Nodes\BreadCrumbNode;
+use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\Nodes\TitleNode;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
+use phpDocumentor\Guides\RenderContext;
+use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
+use phpDocumentor\Guides\RstTheme\Configuration\HeaderSyntax;
+use phpDocumentor\Guides\Twig\GlobalMenuExtension;
+use Psr\Log\LoggerInterface;
+use RuntimeException;
+use Stringable;
+use Twig\Extension\AbstractExtension;
+use Twig\TwigFunction;
+use Twig\TwigTest;
+
+use function sprintf;
+use function trim;
+
+final class RstExtension extends AbstractExtension
+{
+
+    /** @param NodeRenderer<Node> $nodeRenderer */
+    public function __construct(
+        private readonly NodeRenderer $nodeRenderer,
+    ) {
+        $this->menuExtension = new GlobalMenuExtension($this->nodeRenderer);
+    }
+
+    /** @return TwigFunction[] */
+    public function getFunctions(): array
+    {
+        return [
+            new TwigFunction('renderRstTitle', $this->renderRstTitle(...), ['is_safe' => ['rst'], 'needs_context' => false]),
+        ];
+    }
+
+    public function renderRstTitle(TitleNode $node, string $content): string
+    {
+        $headerSyntax = HeaderSyntax::from(min($node->getLevel(), 6));
+        $ret = '';
+        if ($headerSyntax->hasTopDelimiter()) {
+            $ret .= str_repeat($headerSyntax->delimiter(), strlen($content))."\n";
+        }
+        $ret .= $content ."\n" . str_repeat($headerSyntax->delimiter(), strlen($content));
+        return $ret;
+    }
+}

tests/Integration/tests-full/md-to-rst/index-md-to-rst/expected/index.rst

@@ -1,4 +1,3 @@
-
 ================
 Markdown Example
 ================
@@ -9,4 +8,8 @@ Headings
 ========
 
 You can create headings using hash symbols.
-This text is part of a paragraph under the "Headings" heading.
+
+This text is part of a paragraph under the "Headings" heading.
+
+
+

tests/Integration/tests-full/md-to-rst/md-to-rst-list-link/expected/index.rst

@@ -0,0 +1,65 @@
+=========================================
+TYPO3 Extension powermail - Documentation
+=========================================
+
+This documentation helps
+
+*   Administrators to install and configure powermail
+*   Editors to use powermail
+*   Developers to extend powermail
+
+
+Example Screenshots
+===================
+
+Frontend: Show a form with different field types
+------------------------------------------------
+
+..  figure:: Images/frontend1.png
+    :alt: Example form
+
+Example Form with Input, Textarea, Select, Multiselect, Checkboxes, Radiobuttons, and Submit
+
+
+
+Frontend: Multistep Form
+------------------------
+
+..  figure:: Images/frontend2.png
+    :alt: Example form2
+
+Example Multistep Form with clientside validation
+
+
+
+Backend: Mail Listing
+---------------------
+
+..  figure:: Images/backend1.png
+    :alt: backend1
+
+Manage the delivered mails with a fulltext search and some export possibilities
+
+
+
+Backend: Reporting
+------------------
+
+..  figure:: Images/backend2.png
+    :alt: backend2
+
+See the reporting about the delivered mails (Form or Marketing Data Analyses are possible)
+
+
+
+
+
+Documentation overview
+======================
+
+*   `Introduction <https://github.com/in2code-de/powermail/blob/develop/Documentation/Readme.md>`__
+*   `Documentation for editors <https://github.com/in2code-de/powermail/blob/develop/Documentation/ForEditors/Readme.md>`__
+
+
+
+

tests/Integration/tests-full/md-to-rst/md-to-rst-list-link/input/guides.xml

@@ -0,0 +1,11 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+        xsi:schemaLocation="https://www.phpdoc.org/guides packages/guides-cli/resources/schema/guides.xsd"
+        input-format="md"
+        theme="rst"
+>
+    <project title="Project Title" version="6.4"/>
+    <extension class="phpDocumentor\Guides\RstTheme"/>
+    <output-format>rst</output-format>
+</guides>

tests/Integration/tests-full/md-to-rst/md-to-rst-list-link/input/index.md

@@ -0,0 +1,41 @@
+# TYPO3 Extension powermail - Documentation
+
+This documentation helps
+* Administrators to install and configure powermail
+* Editors to use powermail
+* Developers to extend powermail
+
+## Example Screenshots
+
+
+### Frontend: Show a form with different field types
+
+![Example form](Images/frontend1.png "Example Form")
+
+Example Form with Input, Textarea, Select, Multiselect, Checkboxes, Radiobuttons, and Submit
+
+
+### Frontend: Multistep Form
+
+![Example form2](Images/frontend2.png "Example Form with validation")
+
+Example Multistep Form with clientside validation
+
+### Backend: Mail Listing
+
+![backend1](Images/backend1.png)
+
+Manage the delivered mails with a fulltext search and some export possibilities
+
+
+### Backend: Reporting
+
+![backend2](Images/backend2.png)
+
+See the reporting about the delivered mails (Form or Marketing Data Analyses are possible)
+
+
+## Documentation overview
+
+* [Introduction](https://github.com/in2code-de/powermail/blob/develop/Documentation/Readme.md)
+* [Documentation for editors](https://github.com/in2code-de/powermail/blob/develop/Documentation/ForEditors/Readme.md)