Merge pull request #1058 from phpDocumentor/task/rst-theme

[FEATURE] Create a rst theme to render markdown

composer.json

@@ -43,7 +43,8 @@
         "phpdocumentor/guides-graphs": "^2.0@dev || ^1.0",
         "phpdocumentor/guides-markdown": "^2.0@dev || ^1.0",
         "phpdocumentor/guides-restructured-text": "^2.0@dev || ^1.0",
-        "phpdocumentor/guides-theme-bootstrap": "^2.0@dev || ^1.0"
+        "phpdocumentor/guides-theme-bootstrap": "^2.0@dev || ^1.0",
+        "phpdocumentor/guides-theme-rst": "^2.0@dev || ^1.0"
     },
     "require-dev": {
         "ext-dom": "*",

config.subsplit-publish.json

@@ -34,6 +34,11 @@
       "name": "guides-code",
       "directory": "packages/guides-code",
       "target": "[email protected]:phpDocumentor/guides-code.git"
+    },
+    {
+      "name": "guides-theme-rst",
+      "directory": "packages/guides-rst-theme",
+      "target": "[email protected]:phpDocumentor/guides-theme-rst.git"
     }
   ]
 }

deptrac.packages.yaml

@@ -40,6 +40,7 @@ deptrac:
     CLI:
       - "Guides"
       - "RST"
+      - "Markdown"
     RST:
       - "Guides"
     Markdown:

packages/guides-theme-rst/.gitattributes

@@ -0,0 +1,4 @@
+/.gitattributes export-ignore
+/.gitignore export-ignore
+/docs export-ignore
+/tests export-ignore

packages/guides-theme-rst/.gitignore

@@ -0,0 +1 @@
+vendor/*

packages/guides-theme-rst/CONTRIBUTING.rst

@@ -0,0 +1,23 @@
+======================================
+Contribute to the phpDocumentor Guides
+======================================
+
+Go to the mono-repository
+=========================
+
+This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
+The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
+to this repository directly but always to the mono-repository linked above.
+
+Create Issues
+=============
+
+*   If you find something missing or something is wrong in this library, you are welcome to write an issue
+    describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
+*   If you can, please try to fix the problem yourself.
+
+Make changes (create pull requests)
+===================================
+
+See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
+`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-theme-rst/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2010 Mike van Riel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

packages/guides-theme-rst/README.rst

@@ -0,0 +1,37 @@
+
+..  image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/require/php
+    :alt: PHP Version Require
+    :target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
+
+..  image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/v/stable
+    :alt: Latest Stable Version
+    :target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
+
+..  image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/v/unstable
+    :alt: Latest Unstable Version
+    :target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
+
+..  image:: https://poser.pugx.org/phpdocumentor/guides-restructured-text/d/total
+    :alt: Total Downloads
+    :target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
+
+..  image:: https://poser.pugx.org/phpdocumentor/guides-restructured-text/d/monthly
+    :alt: Monthly Downloads
+    :target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
+
+====================
+phpDocumentor Guides
+====================
+
+This repository is part of `phpDocumentor's Guides library <https://github.com/phpDocumentor/guides>`__, a framework
+designed to take hand-written documentation in code repositories and create an AST (abstract syntax tree) from it.
+This AST is then fed to a renderer, which produces the desired output, such as HTML.
+
+The package `phpdocumentor/guides-restructured-text <https://packagist.org/packages/phpdocumentor/guides-restructured-text>`__ adds
+`reStructuredText Markup <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`__ support to the
+phpDocumentor's Guides library.
+
+:Mono-Repository:   https://github.com/phpDocumentor/guides
+:Documentation:     https://github.com/phpDocumentor/guides/tree/main/docs/index.rst
+:Packagist:         https://packagist.org/packages/phpdocumentor/guides-restructured-text
+:Contribution:      https://github.com/phpDocumentor/guides/tree/main/CONTRIBUTING.rst

packages/guides-theme-rst/composer.json

@@ -0,0 +1,32 @@
+{
+    "name": "phpdocumentor/guides-theme-rst",
+    "description": "Adds a reStructuredText theme used to convert Markdown into reStructuredText",
+    "type": "library",
+    "license": "MIT",
+    "homepage": "https://www.phpdoc.org",
+    "config": {
+        "sort-packages": true
+    },
+    "autoload": {
+        "psr-4": {
+            "phpDocumentor\\Guides\\": "src/"
+        }
+    },
+    "autoload-dev": {
+        "psr-4": {
+            "phpDocumentor\\Guides\\": [
+                "tests/unit/"
+            ]
+        }
+    },
+    "minimum-stability": "stable",
+    "require": {
+        "php": "^8.1",
+        "phpdocumentor/guides": "^1.0 || ^2.0"
+    },
+    "extra": {
+        "branch-alias": {
+            "dev-main": "2.x-dev"
+        }
+    }
+}

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

@@ -0,0 +1,34 @@
+<?php
+
+declare(strict_types=1);
+
+use phpDocumentor\Guides\RstTheme\Renderer\RstRenderer;
+use phpDocumentor\Guides\RstTheme\Twig\RstExtension;
+use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
+
+return static function (ContainerConfigurator $container): void {
+    $container->services()
+        ->defaults()
+        ->autowire()
+        ->autoconfigure()
+        /*
+        ->load(
+            'phpDocumentor\\Guides\RstTheme\\NodeRenderers\\Rst\\',
+            '%vendor_dir%/phpdocumentor/guides-rst-theme/src/RstTheme/NodeRenderers/Rst',
+        )
+        ->tag('phpdoc.guides.noderenderer.rst')
+        */
+
+        ->set(RstRenderer::class)
+        ->tag(
+            'phpdoc.renderer.typerenderer',
+            [
+                'noderender_tag' => 'phpdoc.guides.noderenderer.rst',
+                'format' => 'rst',
+            ],
+        )
+
+        ->set(RstExtension::class)
+        ->tag('twig.extension')
+        ->autowire();
+};

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

@@ -0,0 +1,6 @@
+..  code-block:: plaintext
+
+{{ renderRstIndent(node.value|raw, 1)|raw }}
+{{ "\n" }}
+{{ "\n" }}
+

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

@@ -0,0 +1,11 @@
+{{ "\n" }}
+{% if node.isOrdered -%}
+    {%- for item in node.value -%}
+        #.  {{ renderNode(item.value)|raw }}{{ "\n" }}
+    {% endfor -%}
+{%- else -%}
+    {%- for item in node.value -%}
+        *   {{ renderNode(item.value)|raw }}{{ "\n" }}
+    {%- endfor -%}
+{%- endif %}
+{{ "\n" }}

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

@@ -0,0 +1,6 @@
+{% set text = renderNode(node.value)|raw -%}
+{%- if text|trim %}
+    {{- text|raw -}}
+{% endif -%}
+{{ "\n" }}
+{{ "\n" }}

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

@@ -0,0 +1,3 @@
+{{ renderRstIndent(renderNode(node.value)|raw, 1)|raw }}
+{{ "\n" }}
+{{ "\n" }}

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

@@ -0,0 +1 @@
+====

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

@@ -0,0 +1 @@
+\\\\\\\\\n

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

@@ -0,0 +1 @@
+\textit{{ '{' }}{{ text|raw }}{{ '}' }}

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

@@ -0,0 +1,5 @@
+{% if type == 'ref' %}
+\ref{{ '{' }}{{ url }}{{ '}' }}
+{% else %}
+\href{{ '{' }}{{ url }}{{ '}' }}{{ '{' }}{{ title }}{{ '}' }}
+{% endif %}

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

@@ -0,0 +1 @@
+\verb|{{ node.value|raw }}|

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

@@ -0,0 +1 @@
+~

packages/guides-theme-rst/resources/template/rst/guides/inline/strong-emphasis.rst.twig

@@ -0,0 +1 @@
+\textbf{{ '{' }}{{ text|raw }}{{ '}' }}

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

@@ -0,0 +1 @@
+\{{ type }}{{ '{' }}{{ renderNode(titleNode.value) }}{{ '}' }}

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

@@ -0,0 +1 @@
+*{{- node.value|raw -}}*

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

@@ -0,0 +1,4 @@
+{{ "\n" }}
+..  figure:: {{ node.url|raw }}
+    :alt: {{ node.altText|raw }}
+{{ "\n" }}

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

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

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

@@ -0,0 +1,5 @@
+{%- if node.value matches '/`/' -%}
+    ``{{- node.value|raw -}}``
+{%- else -%}
+    `{{- node.value|raw -}}`
+{%- endif -%}

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

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

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

@@ -0,0 +1 @@
+**{{- node.value|raw -}}**

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

@@ -0,0 +1,7 @@
+{%- set renderedContent -%}
+    {%- for child in node.children -%}
+        {{- renderNode(child) -}}
+    {%- endfor -%}
+{%- endset -%}
+
+{{- renderedContent | clean_content | raw -}}

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

@@ -0,0 +1 @@
+{{ renderRstTitle(node, renderNode(node.value)) }}

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

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

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

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