Skip to content

Commit c50c94a

Browse files
linawolflinawolf
committed
[FEATURE] Add Meta-information markup
https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#meta-information-markup resolves #847
1 parent b59ff9e commit c50c94a

File tree

14 files changed

+246
-36
lines changed

14 files changed

+246
-36
lines changed

‎packages/guides-restructured-text/resources/config/guides-restructured-text.php

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,7 @@
4343
use phpDocumentor\Guides\RestructuredText\Directives\RawDirective;
4444
use phpDocumentor\Guides\RestructuredText\Directives\ReplaceDirective;
4545
use phpDocumentor\Guides\RestructuredText\Directives\RoleDirective;
46+
use phpDocumentor\Guides\RestructuredText\Directives\SectionauthorDirective;
4647
use phpDocumentor\Guides\RestructuredText\Directives\SeeAlsoDirective;
4748
use phpDocumentor\Guides\RestructuredText\Directives\SidebarDirective;
4849
use phpDocumentor\Guides\RestructuredText\Directives\SubDirective;
@@ -216,6 +217,7 @@
216217
->set(RawDirective::class)
217218
->set(ReplaceDirective::class)
218219
->set(RoleDirective::class)
220+
->set(SectionauthorDirective::class)
219221
->set(SeeAlsoDirective::class)
220222
->set(SidebarDirective::class)
221223
->set(TableDirective::class)

‎packages/guides-restructured-text/src/RestructuredText/Directives/SectionauthorDirective.php

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\RestructuredText\Directives;
15+
16+
use phpDocumentor\Guides\Nodes\AuthorNode;
17+
use phpDocumentor\Guides\Nodes\Node;
18+
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
19+
use phpDocumentor\Guides\RestructuredText\Parser\Directive;
20+
use Psr\Log\LoggerInterface;
21+
22+
use function preg_match;
23+
24+
final class SectionauthorDirective extends BaseDirective
25+
{
26+
public const NAME_EMAIL_REGEX = '/^(?P<name>[\w\s]+)(?: <(?P<email>[^>]+)>)?$/';
27+
28+
public function __construct(
29+
private readonly LoggerInterface $logger,
30+
) {
31+
}
32+
33+
public function getName(): string
34+
{
35+
return 'sectionauthor';
36+
}
37+
38+
/**
39+
* When the default domain contains a class directive, this directive will be shadowed. Therefore, Sphinx re-exports it as rst-class.
40+
*
41+
* See https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#rstclass
42+
*
43+
* @return string[]
44+
*/
45+
public function getAliases(): array
46+
{
47+
return ['codeauthor'];
48+
}
49+
50+
/** {@inheritDoc}
51+
*
52+
* @param Directive $directive
53+
*/
54+
public function process(
55+
BlockContext $blockContext,
56+
Directive $directive,
57+
): Node|null {
58+
$input = $directive->getData();
59+
$directiveName = $directive->getName();
60+
if ($input === '') {
61+
$this->logger->warning('`.. ' . $directiveName . ' ::` directive could not be parsed: `' . $input . '`', $blockContext->getLoggerInformation());
62+
63+
return null;
64+
}
65+
66+
if (!preg_match(self::NAME_EMAIL_REGEX, $input, $matches)) {
67+
$this->logger->warning('Content of `.. ' . $directiveName . ':: name <email>` must specify a name and can also specify an email', $blockContext->getLoggerInformation());
68+
69+
return null;
70+
}
71+
72+
$name = $matches['name'];
73+
$email = $matches['email'] ?? null;
74+
$context = match ($directiveName) {
75+
'sectionauthor' => AuthorNode::CONTEXT_SECTION,
76+
default => AuthorNode::CONTEXT_CODE,
77+
};
78+
79+
return new AuthorNode($name, [], $context, $email);
80+
}
81+
}

‎packages/guides/resources/template/html/body/author.html.twig

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
<address itemprop="author" itemscope itemtype="http://schema.org/Person">
2+
<p>Author: <span itemprop="name">{node.value}</span></p>
3+
<p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
4+
</address>

‎packages/guides/resources/template/html/template.php

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,7 @@
5757

5858
return [
5959
AnchorNode::class => 'inline/anchor.html.twig',
60+
\phpDocumentor\Guides\Nodes\AuthorNode::class => 'body/author.html.twig',
6061
FigureNode::class => 'body/figure.html.twig',
6162
MetaNode::class => 'structure/header/meta.html.twig',
6263
ParagraphNode::class => 'body/paragraph.html.twig',

‎packages/guides/src/Nodes/AuthorNode.php

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
/**
6+
* This file is part of phpDocumentor.
7+
*
8+
* For the full copyright and license information, please view the LICENSE
9+
* file that was distributed with this source code.
10+
*
11+
* @link https://phpdoc.org
12+
*/
13+
14+
namespace phpDocumentor\Guides\Nodes;
15+
16+
use function filter_var;
17+
18+
use const FILTER_VALIDATE_EMAIL;
19+
20+
/**
21+
* The author element holds the name of the author of a document, section or code-block
22+
*
23+
* @extends AbstractNode<string>
24+
*/
25+
final class AuthorNode extends AbstractNode
26+
{
27+
public const CONTEXT_DOCUMENT = 'document';
28+
public const CONTEXT_SECTION = 'section';
29+
public const CONTEXT_CODE = 'code';
30+
31+
/** @param Node[] $children */
32+
public function __construct(
33+
string $value,
34+
private readonly array $children,
35+
private readonly string $context = self::CONTEXT_DOCUMENT,
36+
private string|null $email = null,
37+
) {
38+
$this->value = $value;
39+
if (filter_var($email ?? '', FILTER_VALIDATE_EMAIL)) {
40+
return;
41+
}
42+
43+
$this->email = null;
44+
}
45+
46+
/** @return Node[] */
47+
public function getChildren(): array
48+
{
49+
return $this->children;
50+
}
51+
52+
public function getEmail(): string|null
53+
{
54+
return $this->email;
55+
}
56+
57+
public function getContext(): string
58+
{
59+
return $this->context;
60+
}
61+
}

‎tests/Integration/tests/body-elements/line-blocks/expected/index.html

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,41 @@
11
<!-- content start -->
22
<div class="section" id="line-blocks">
3-
<h1>Line Blocks</h1>
3+
<h1>Line Blocks</h1>
44

5-
<div class="line-block">
6-
<div class="line">
7-
Line blocks are useful for addresses,
8-
</div>
9-
<div class="line">
10-
verse, and adornment-free lists.
11-
</div>
12-
<div class="line">
13-
<br>
14-
</div>
15-
<div class="line">
16-
Each new line begins with a
17-
</div>
18-
<div class="line">
19-
vertical bar (&quot;|&quot;).
20-
</div>
215
<div class="line-block">
22-
<div class="line">
23-
Line breaks and initial indents
24-
</div>
25-
<div class="line">
26-
are preserved.
27-
</div>
28-
</div>
29-
<div class="line">
30-
Continuation lines are wrapped
31-
portions of long lines; they begin
32-
with spaces in place of vertical bars.
33-
</div>
34-
</div>
35-
<p>This is normal text</p>
6+
<div class="line">
7+
Line blocks are useful for addresses,
8+
</div>
9+
<div class="line">
10+
verse, and adornment-free lists.
11+
</div>
12+
<div class="line">
13+
<br>
14+
</div>
15+
<div class="line">
16+
Each new line begins with a
17+
</div>
18+
<div class="line">
19+
vertical bar (&quot;|&quot;).
20+
</div>
21+
<div class="line-block">
22+
<div class="line">
23+
Line breaks and initial indents
24+
</div>
25+
<div class="line">
26+
are preserved.
27+
</div>
28+
29+
</div>
30+
<div class="line">
31+
Continuation lines are wrapped
32+
portions of long lines; they begin
33+
with spaces in place of vertical bars.
34+
</div>
35+
36+
</div>
37+
38+
<p>This is normal text</p>
3639
</div>
3740

3841
<!-- content end -->

‎tests/Integration/tests/directives/sectionauthor/expected/index.html

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
<!-- content start -->
2+
<div class="section" id="document-title">
3+
<h1>Document Title</h1>
4+
5+
<div class="section" id="some-section">
6+
<h2>Some Section</h2>
7+
8+
<address itemprop="author" itemscope itemtype="http://schema.org/Person">
9+
<p>Author: <span itemprop="name">{node.value}</span></p>
10+
<p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
11+
</address>
12+
13+
</div>
14+
15+
<div class="section" id="some-other-section">
16+
<h2>Some other section</h2>
17+
18+
<address itemprop="author" itemscope itemtype="http://schema.org/Person">
19+
<p>Author: <span itemprop="name">{node.value}</span></p>
20+
<p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
21+
</address>
22+
23+
<address itemprop="author" itemscope itemtype="http://schema.org/Person">
24+
<p>Author: <span itemprop="name">{node.value}</span></p>
25+
<p>Email: <a href="mailto:{node.email}"><span itemprop="email">{node.email}</span></a></p>
26+
</address>
27+
28+
<pre><code class="language-rst">Lorem *Ipsum* Dolor</code></pre>
29+
</div>
30+
31+
</div>
32+
33+
<!-- content end -->

‎tests/Integration/tests/directives/sectionauthor/input/index.rst

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
==============
2+
Document Title
3+
==============
4+
5+
Some Section
6+
============
7+
8+
.. sectionauthor:: Lina Wolf <[email protected]>
9+
10+
Some other section
11+
==================
12+
13+
.. sectionauthor:: Lina Wolf
14+
15+
.. codeauthor:: Lina Wolf <[email protected]>
16+
17+
.. code-block:: rst
18+
19+
Lorem *Ipsum* Dolor

‎tests/Integration/tests/directives/youtube/expected/index.html

Lines changed: 6 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,10 @@
11
<!-- content start -->
2-
<div class="section" id="document-title">
3-
<h1>Document Title</h1>
2+
<div class="section" id="document-title">
3+
<h1>Document Title</h1>
44

5-
<iframe src="https://www.youtube-nocookie.com/embed/hdDD0SNJ-pk" width="560" height="315" title="PHP DocBlock - Adding Comments to Classes &amp; Methods" allow="encrypted-media; picture-in-picture; web-share" allowfullscreen>
6-
</iframe>
5+
<iframe src="https://www.youtube-nocookie.com/embed/hdDD0SNJ-pk" width="560" height="315" title="PHP DocBlock - Adding Comments to Classes &amp; Methods" allow="encrypted-media; picture-in-picture; web-share" allowfullscreen>
6+
</iframe>
7+
8+
</div>
79

8-
</div>
910
<!-- content end -->

‎tests/Integration/tests/images/figure-relative/expected/index.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,7 @@ <h2>An image with relative paths</h2>
4949
</figcaption>
5050
</figure>
5151

52+
5253
</div>
5354

5455
</div>

‎tests/Integration/tests/images/figure-relative/expected/subfolder/subpage.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ <h2>An image with relative paths</h2>
3333
</figcaption>
3434
</figure>
3535

36+
3637
</div>
3738

3839
</div>

‎tests/Integration/tests/images/image-absolute/expected/index.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ <h2>An image with relative paths</h2>
2828
src="/images/hero2-illustration.svg"
2929
width="400" alt="Alternative text" />
3030

31+
3132
</div>
3233

3334
</div>

‎tests/Integration/tests/images/image-relative/expected/index.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ <h2>An image with relative paths</h2>
2828
src="images/hero2-illustration.svg"
2929
width="400" alt="Alternative text" />
3030

31+
3132
</div>
3233

3334
</div>

‎tests/Integration/tests/images/image-relative/expected/subfolder/subpage.html

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ <h2>An image with relative paths</h2>
1919
src="../images/hero2-illustration.svg"
2020
width="400" alt="Alternative text" />
2121

22+
2223
</div>
2324

2425
</div>

0 commit comments

Comments
 (0)