Skip to content

Commit 7dc8588

Browse files
committed
[FEATURE] Create a rst theme to convert markdown
Convert basic mark-down into restructured Text * headlines * paragpraphs * links * lists * emphasis * inline-code
1 parent f7aeefe commit 7dc8588

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

50 files changed

+702
-1
lines changed

composer.json

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,8 @@
4343
"phpdocumentor/guides-graphs": "^2.0@dev || ^1.0",
4444
"phpdocumentor/guides-markdown": "^2.0@dev || ^1.0",
4545
"phpdocumentor/guides-restructured-text": "^2.0@dev || ^1.0",
46-
"phpdocumentor/guides-theme-bootstrap": "^2.0@dev || ^1.0"
46+
"phpdocumentor/guides-theme-bootstrap": "^2.0@dev || ^1.0",
47+
"phpdocumentor/guides-theme-rst": "^2.0@dev || ^1.0"
4748
},
4849
"require-dev": {
4950
"ext-dom": "*",

config.subsplit-publish.json

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -34,6 +34,11 @@
3434
"name": "guides-code",
3535
"directory": "packages/guides-code",
3636
"target": "[email protected]:phpDocumentor/guides-code.git"
37+
},
38+
{
39+
"name": "guides-theme-rst",
40+
"directory": "packages/guides-rst-theme",
41+
"target": "[email protected]:phpDocumentor/guides-theme-rst.git"
3742
}
3843
]
3944
}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
/.gitattributes export-ignore
2+
/.gitignore export-ignore
3+
/docs export-ignore
4+
/tests export-ignore

packages/guides-theme-rst/.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
vendor/*
Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
======================================
2+
Contribute to the phpDocumentor Guides
3+
======================================
4+
5+
Go to the mono-repository
6+
=========================
7+
8+
This project is developed in the mono-repository `phpDocumentor Guides <https://github.com/phpDocumentor/guides>`__.
9+
The repository you are currently in gets auto-created by splitting the mono-repository. You **must not** contribute
10+
to this repository directly but always to the mono-repository linked above.
11+
12+
Create Issues
13+
=============
14+
15+
* If you find something missing or something is wrong in this library, you are welcome to write an issue
16+
describing the problem: `Issues on GitHub <https://github.com/phpDocumentor/guides/issues>`__.
17+
* If you can, please try to fix the problem yourself.
18+
19+
Make changes (create pull requests)
20+
===================================
21+
22+
See the `Contribution chapter <https://github.com/phpDocumentor/guides/tree/main/docs/contributions/index.rst>`__ in the
23+
`Documentation` <https://github.com/phpDocumentor/guides/tree/main/docs/index.rst>`__.

packages/guides-theme-rst/LICENSE

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

packages/guides-theme-rst/README.rst

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
2+
.. image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/require/php
3+
:alt: PHP Version Require
4+
:target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
5+
6+
.. image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/v/stable
7+
:alt: Latest Stable Version
8+
:target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
9+
10+
.. image:: http://poser.pugx.org/phpdocumentor/guides-restructured-text/v/unstable
11+
:alt: Latest Unstable Version
12+
:target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
13+
14+
.. image:: https://poser.pugx.org/phpdocumentor/guides-restructured-text/d/total
15+
:alt: Total Downloads
16+
:target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
17+
18+
.. image:: https://poser.pugx.org/phpdocumentor/guides-restructured-text/d/monthly
19+
:alt: Monthly Downloads
20+
:target: https://packagist.org/packages/phpdocumentor/guides-restructured-text
21+
22+
====================
23+
phpDocumentor Guides
24+
====================
25+
26+
This repository is part of `phpDocumentor's Guides library <https://github.com/phpDocumentor/guides>`__, a framework
27+
designed to take hand-written documentation in code repositories and create an AST (abstract syntax tree) from it.
28+
This AST is then fed to a renderer, which produces the desired output, such as HTML.
29+
30+
The package `phpdocumentor/guides-restructured-text <https://packagist.org/packages/phpdocumentor/guides-restructured-text>`__ adds
31+
`reStructuredText Markup <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`__ support to the
32+
phpDocumentor's Guides library.
33+
34+
:Mono-Repository: https://github.com/phpDocumentor/guides
35+
:Documentation: https://github.com/phpDocumentor/guides/tree/main/docs/index.rst
36+
:Packagist: https://packagist.org/packages/phpdocumentor/guides-restructured-text
37+
:Contribution: https://github.com/phpDocumentor/guides/tree/main/CONTRIBUTING.rst
Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "phpdocumentor/guides-theme-rst",
3+
"description": "Adds a reStructuredText theme used to convert Markdown into reStructuredText",
4+
"type": "library",
5+
"license": "MIT",
6+
"homepage": "https://www.phpdoc.org",
7+
"config": {
8+
"sort-packages": true
9+
},
10+
"autoload": {
11+
"psr-4": {
12+
"phpDocumentor\\Guides\\": "src/"
13+
}
14+
},
15+
"autoload-dev": {
16+
"psr-4": {
17+
"phpDocumentor\\Guides\\": [
18+
"tests/unit/"
19+
]
20+
}
21+
},
22+
"minimum-stability": "stable",
23+
"require": {
24+
"php": "^8.1",
25+
"phpdocumentor/guides": "^1.0 || ^2.0"
26+
},
27+
"extra": {
28+
"branch-alias": {
29+
"dev-main": "2.x-dev"
30+
}
31+
}
32+
}
Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use phpDocumentor\Guides\RstTheme\Renderer\RstRenderer;
6+
use phpDocumentor\Guides\RstTheme\Twig\RstExtension;
7+
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
8+
9+
use function Symfony\Component\DependencyInjection\Loader\Configurator\service;
10+
11+
return static function (ContainerConfigurator $container): void {
12+
$container->services()
13+
->defaults()
14+
->autowire()
15+
->autoconfigure()
16+
/*
17+
->load(
18+
'phpDocumentor\\Guides\RstTheme\\NodeRenderers\\Rst\\',
19+
'%vendor_dir%/phpdocumentor/guides-rst-theme/src/RstTheme/NodeRenderers/Rst',
20+
)
21+
->tag('phpdoc.guides.noderenderer.rst')
22+
*/
23+
24+
->set(RstRenderer::class)
25+
->tag(
26+
'phpdoc.renderer.typerenderer',
27+
[
28+
'noderender_tag' => 'phpdoc.guides.noderenderer.rst',
29+
'format' => 'rst',
30+
],
31+
)
32+
33+
->set(RstExtension::class)
34+
->arg('$nodeRenderer', service('phpdoc.guides.output_node_renderer'))
35+
->tag('twig.extension')
36+
->autowire();
37+
};
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
```
2+
{{ node.value|raw }}
3+
```
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
{% if node.isOrdered -%}
2+
{%- for item in node.value -%}
3+
#. {{ renderNode(item.value)|raw }}{{ "\n\n" }}
4+
{% endfor -%}
5+
{%- else -%}
6+
{%- for item in node.value -%}
7+
* {{ renderNode(item.value)|raw }}{{ "\n" }}
8+
{%- endfor -%}
9+
{%- endif -%}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{%- set text = renderNode(node.value)|raw -%}
2+
{%- if text|trim %}
3+
{{- text|raw -}}
4+
{% endif -%}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ renderNode(node.value) }}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
====
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\\\\\\\\\n
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\textit{{ '{' }}{{ text|raw }}{{ '}' }}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{% if type == 'ref' %}
2+
\ref{{ '{' }}{{ url }}{{ '}' }}
3+
{% else %}
4+
\href{{ '{' }}{{ url }}{{ '}' }}{{ '{' }}{{ title }}{{ '}' }}
5+
{% endif %}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\verb|{{ node.value|raw }}|
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
~
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\textbf{{ '{' }}{{ text|raw }}{{ '}' }}

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

Whitespace-only changes.
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
\{{ type }}{{ '{' }}{{ renderNode(titleNode.value) }}{{ '}' }}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
*{{- node.value|raw -}}*
Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.. figure:: {{ node.url }}
2+
:alt: {{ node.altText }}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{%- for child in node.children -%}
2+
{{- renderNode(child) -}}
3+
{%- endfor -%}
Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{%- if node.url -%}
2+
`{{ node.value|raw }} <{{- node.url -}}>`__
3+
{%- elseif node.targetReference -%}
4+
:doc:`{{ node.value|raw }} <{{- node.targetReference -}}>`
5+
{%- else -%}
6+
{{- node.value -}}
7+
{%- endif -%}
Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
{%- if node.value matches '/`/' -%}
2+
``{{- node.value -}}``
3+
{%- else -%}
4+
`{{- node.value -}}`
5+
{%- endif -%}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{- node.value|raw -}}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
**{{- node.value|raw -}}**
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{% for child in node.children -%}
2+
{{- renderNode(child) -}}
3+
{%- endfor %}
Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
{{ renderRstTitle(node, renderNode(node.value)) }}
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{%- for document in documents %}
2+
{{- renderNode(document) }}
3+
{%- endfor -%}
Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{% for childNode in node.children -%}
2+
{{- renderNode(childNode) }}
3+
4+
{% endfor -%}
Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use phpDocumentor\Guides\Nodes\AnchorNode;
6+
use phpDocumentor\Guides\Nodes\AnnotationListNode;
7+
use phpDocumentor\Guides\Nodes\CitationNode;
8+
use phpDocumentor\Guides\Nodes\CodeNode;
9+
use phpDocumentor\Guides\Nodes\DefinitionListNode;
10+
use phpDocumentor\Guides\Nodes\DefinitionLists\DefinitionNode;
11+
use phpDocumentor\Guides\Nodes\DocumentNode;
12+
use phpDocumentor\Guides\Nodes\FieldListNode;
13+
use phpDocumentor\Guides\Nodes\FigureNode;
14+
use phpDocumentor\Guides\Nodes\FootnoteNode;
15+
use phpDocumentor\Guides\Nodes\ImageNode;
16+
use phpDocumentor\Guides\Nodes\Inline\AbbreviationInlineNode;
17+
use phpDocumentor\Guides\Nodes\Inline\CitationInlineNode;
18+
use phpDocumentor\Guides\Nodes\Inline\DocReferenceNode;
19+
use phpDocumentor\Guides\Nodes\Inline\EmphasisInlineNode;
20+
use phpDocumentor\Guides\Nodes\Inline\FootnoteInlineNode;
21+
use phpDocumentor\Guides\Nodes\Inline\GenericTextRoleInlineNode;
22+
use phpDocumentor\Guides\Nodes\Inline\HyperLinkNode;
23+
use phpDocumentor\Guides\Nodes\Inline\ImageInlineNode;
24+
use phpDocumentor\Guides\Nodes\Inline\LiteralInlineNode;
25+
use phpDocumentor\Guides\Nodes\Inline\NewlineInlineNode;
26+
use phpDocumentor\Guides\Nodes\Inline\PlainTextInlineNode;
27+
use phpDocumentor\Guides\Nodes\Inline\ReferenceNode;
28+
use phpDocumentor\Guides\Nodes\Inline\StrongInlineNode;
29+
use phpDocumentor\Guides\Nodes\Inline\VariableInlineNode;
30+
use phpDocumentor\Guides\Nodes\Inline\WhitespaceInlineNode;
31+
use phpDocumentor\Guides\Nodes\InlineCompoundNode;
32+
use phpDocumentor\Guides\Nodes\ListItemNode;
33+
use phpDocumentor\Guides\Nodes\ListNode;
34+
use phpDocumentor\Guides\Nodes\LiteralBlockNode;
35+
use phpDocumentor\Guides\Nodes\Metadata\AddressNode;
36+
use phpDocumentor\Guides\Nodes\Metadata\AuthorNode;
37+
use phpDocumentor\Guides\Nodes\Metadata\AuthorsNode;
38+
use phpDocumentor\Guides\Nodes\Metadata\ContactNode;
39+
use phpDocumentor\Guides\Nodes\Metadata\CopyrightNode;
40+
use phpDocumentor\Guides\Nodes\Metadata\DateNode;
41+
use phpDocumentor\Guides\Nodes\Metadata\MetaNode;
42+
use phpDocumentor\Guides\Nodes\Metadata\NoCommentsNode;
43+
use phpDocumentor\Guides\Nodes\Metadata\NoSearchNode;
44+
use phpDocumentor\Guides\Nodes\Metadata\OrganizationNode;
45+
use phpDocumentor\Guides\Nodes\Metadata\OrphanNode;
46+
use phpDocumentor\Guides\Nodes\Metadata\RevisionNode;
47+
use phpDocumentor\Guides\Nodes\Metadata\TocDepthNode;
48+
use phpDocumentor\Guides\Nodes\Metadata\TopicNode;
49+
use phpDocumentor\Guides\Nodes\Metadata\VersionNode;
50+
use phpDocumentor\Guides\Nodes\ParagraphNode;
51+
use phpDocumentor\Guides\Nodes\QuoteNode;
52+
use phpDocumentor\Guides\Nodes\SectionNode;
53+
use phpDocumentor\Guides\Nodes\SeparatorNode;
54+
use phpDocumentor\Guides\Nodes\TitleNode;
55+
56+
return [
57+
AnchorNode::class => 'inline/anchor.rst.twig',
58+
FigureNode::class => 'body/figure.rst.twig',
59+
MetaNode::class => 'structure/header/meta.rst.twig',
60+
ParagraphNode::class => 'body/paragraph.rst.twig',
61+
QuoteNode::class => 'body/quote.rst.twig',
62+
SeparatorNode::class => 'body/separator.rst.twig',
63+
TitleNode::class => 'structure/header-title.rst.twig',
64+
SectionNode::class => 'structure/section.rst.twig',
65+
DocumentNode::class => 'structure/document.rst.twig',
66+
ImageNode::class => 'body/image.rst.twig',
67+
CodeNode::class => 'body/code.rst.twig',
68+
DefinitionListNode::class => 'body/definition-list.rst.twig',
69+
DefinitionNode::class => 'body/definition.rst.twig',
70+
FieldListNode::class => 'body/field-list.rst.twig',
71+
ListNode::class => 'body/list/list.rst.twig',
72+
ListItemNode::class => 'body/list/list-item.rst.twig',
73+
LiteralBlockNode::class => 'body/literal-block.rst.twig',
74+
CitationNode::class => 'body/citation.rst.twig',
75+
FootnoteNode::class => 'body/footnote.rst.twig',
76+
AnnotationListNode::class => 'body/annotation-list.rst.twig',
77+
// Inline
78+
ImageInlineNode::class => 'inline/image.rst.twig',
79+
InlineCompoundNode::class => 'inline/inline-node.rst.twig',
80+
AbbreviationInlineNode::class => 'inline/textroles/abbreviation.rst.twig',
81+
CitationInlineNode::class => 'inline/citation.rst.twig',
82+
DocReferenceNode::class => 'inline/doc.rst.twig',
83+
EmphasisInlineNode::class => 'inline/emphasis.rst.twig',
84+
FootnoteInlineNode::class => 'inline/footnote.rst.twig',
85+
HyperLinkNode::class => 'inline/link.rst.twig',
86+
LiteralInlineNode::class => 'inline/literal.rst.twig',
87+
NewlineInlineNode::class => 'inline/newline.rst.twig',
88+
WhitespaceInlineNode::class => 'inline/nbsp.rst.twig',
89+
PlainTextInlineNode::class => 'inline/plain-text.rst.twig',
90+
ReferenceNode::class => 'inline/ref.rst.twig',
91+
StrongInlineNode::class => 'inline/strong.rst.twig',
92+
VariableInlineNode::class => 'inline/variable.rst.twig',
93+
GenericTextRoleInlineNode::class => 'inline/textroles/generic.rst.twig',
94+
// Output as Metatags
95+
AuthorNode::class => 'structure/header/author.rst.twig',
96+
CopyrightNode::class => 'structure/header/copyright.rst.twig',
97+
DateNode::class => 'structure/header/date.rst.twig',
98+
NoSearchNode::class => 'structure/header/no-search.rst.twig',
99+
TopicNode::class => 'structure/header/topic.rst.twig',
100+
// No output in page header in tex - might be output in i.e. LaTex
101+
AddressNode::class => 'structure/header/blank.rst.twig',
102+
AuthorsNode::class => 'structure/header/blank.rst.twig',
103+
ContactNode::class => 'structure/header/blank.rst.twig',
104+
NoCommentsNode::class => 'structure/header/blank.rst.twig',
105+
OrganizationNode::class => 'structure/header/blank.rst.twig',
106+
OrphanNode::class => 'structure/header/blank.rst.twig',
107+
RevisionNode::class => 'structure/header/blank.rst.twig',
108+
TocDepthNode::class => 'structure/header/blank.rst.twig',
109+
VersionNode::class => 'structure/header/blank.rst.twig',
110+
];

0 commit comments

Comments
 (0)