Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -261,7 +261,7 @@
->set(TabsDirective::class)
->set(TitleDirective::class)
->set(ToctreeDirective::class)
->bind('$startingRule', service(InlineMarkupRule::class))
->bind('$startingRule', inline_service(SettingsManager::class))
->set(MenuDirective::class)
->set(TodoDirective::class)
->set(VersionAddedDirective::class)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -54,12 +54,12 @@ public function process(
BlockContext $blockContext,
Directive $directive,
): Node {
$parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
$options = $directive->getOptions();
$options['glob'] = new DirectiveOption('glob', true);
$indexName = $this->settingsManager->getProjectSettings()->getIndexName();
$options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);

$parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
$toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
$parserContext,
$blockContext->getDocumentIterator(),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -13,12 +13,16 @@

namespace phpDocumentor\Guides\RestructuredText\Directives;

use Doctrine\Deprecations\Deprecation;
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
use phpDocumentor\Guides\Nodes\InlineCompoundNode;
use phpDocumentor\Guides\Nodes\Menu\TocNode;
use phpDocumentor\Guides\Nodes\Node;
use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
use phpDocumentor\Guides\RestructuredText\Parser\Directive;
use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Directive as DirectiveAttribute;
use phpDocumentor\Guides\RestructuredText\Directives\Attributes\Option;
use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
use phpDocumentor\Guides\Settings\ProjectSettings;
Expand Down Expand Up @@ -70,50 +74,56 @@
* :maxdepth:
* Synonym of :depth:, depth prevails if both are set.
*/
#[DirectiveAttribute(name: 'toctree', rawContent: true)]
#[Option(name: 'caption', type: OptionType::InlineMarkup)]
#[Option(name: 'depth', type: OptionType::Integer)]
#[Option(name: 'glob', type: OptionType::Boolean)]
#[Option(name: 'globExclude')]
#[Option(name: 'hidden', type: OptionType::Boolean)]
#[Option(name: 'reversed', type: OptionType::Boolean)]
#[Option(name: 'titlesonly', type: OptionType::Boolean)]
#[Option(name: 'maxdepth', type: OptionType::Integer)]
final class ToctreeDirective extends BaseDirective
{
private SettingsManager $settingsManager;

/** @param Rule<InlineCompoundNode> $startingRule */
/** @param Rule<InlineCompoundNode>|SettingsManager $startingRule */
public function __construct(
private readonly ToctreeBuilder $toctreeBuilder,
private readonly Rule $startingRule,
Rule|SettingsManager $startingRule,
SettingsManager|null $settingsManager = null,
) {
// if for backward compatibility reasons no settings manager was passed, use the defaults
if ($startingRule instanceof Rule) {
Deprecation::trigger(
'phpdocumentor/guide-restructured-text',
'https://github.com/phpDocumentor/guides/issues/1373',
'Passing a Rule to ToctreeDirective is deprecated; pass a SettingsManager instead.',
);
} else {
$settingsManager ??= $startingRule;
}

$this->settingsManager = $settingsManager ?? new SettingsManager(new ProjectSettings());
}

public function getName(): string
public function createNode(DirectiveNode $directiveNode, CompilerContextInterface $compilerContext): Node
{
return 'toctree';
}

/** {@inheritDoc} */
public function process(
BlockContext $blockContext,
Directive $directive,
): Node {
$parserContext = $blockContext->getDocumentParserContext()->getParser()->getParserContext();
$directive = $directiveNode->getDirective();
$options = $directive->getOptions();
$indexName = $this->settingsManager->getProjectSettings()->getIndexName();
$options['globExclude'] ??= new DirectiveOption('globExclude', $indexName);

$toctreeFiles = $this->toctreeBuilder->buildToctreeEntries(
$parserContext,
$blockContext->getDocumentIterator(),
$options,
);

$tocNode = (new TocNode($toctreeFiles))->withOptions($this->optionsToArray($options));
$lines = new LinesIterator();
$lines->load($directiveNode->getRawContent(), true);
$toctreeFiles = $this->toctreeBuilder->buildToctreeEntriesFromLines($lines, $options);

if (isset($options['caption'])) {
$blockContextOfCaption = new BlockContext($blockContext->getDocumentParserContext(), (string) $options['caption']->getValue(), false, $blockContext->getLineOffset(0));
$inlineNode = $this->startingRule->apply($blockContextOfCaption);
$tocNode = $tocNode->withCaption($inlineNode);
$tocNode = (new TocNode($toctreeFiles))->withOptions($this->optionsToArray($options));
$caption = $this->readOption($directive, 'caption');
if ($caption instanceof InlineCompoundNode) {
$tocNode = $tocNode->withCaption($caption);
}

if ($directive->getOptionBool('reversed')) {
if ($this->readOption($directive, 'reversed') === true) {
$tocNode = $tocNode->withReversed(true);
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,7 @@

use const FILTER_VALIDATE_URL;

/** @internal This class is not part of the public API and should not be used by third-party code. */
final class ToctreeBuilder
{
use EmbeddedReferenceParser;
Expand All @@ -42,6 +43,20 @@ public function buildToctreeEntries(
ParserContext $parserContext,
LinesIterator $lines,
array $options,
): array {
return $this->buildToctreeEntriesFromLines($lines, $options);
}

/**
* Builds entries from directive content already captured by the parser.
*
* @param mixed[] $options
*
* @return MenuEntryNode[]
*/
public function buildToctreeEntriesFromLines(
LinesIterator $lines,
array $options,
): array {
$toctreeEntries = [];

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,109 @@
<?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\RestructuredText\Directives;

use Doctrine\Deprecations\PHPUnit\VerifyDeprecations;
use phpDocumentor\Guides\Compiler\CompilerContextInterface;
use phpDocumentor\Guides\Nodes\InlineCompoundNode;
use phpDocumentor\Guides\Nodes\Menu\TocNode;
use phpDocumentor\Guides\RestructuredText\Nodes\DirectiveNode;
use phpDocumentor\Guides\RestructuredText\Parser\Directive;
use phpDocumentor\Guides\RestructuredText\Parser\DirectiveOption;
use phpDocumentor\Guides\RestructuredText\Parser\Productions\Rule;
use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
use phpDocumentor\Guides\Settings\ProjectSettings;
use phpDocumentor\Guides\Settings\SettingsManager;
use PHPUnit\Framework\Attributes\WithoutErrorHandler;
use PHPUnit\Framework\TestCase;

final class ToctreeDirectiveTest extends TestCase
{
use VerifyDeprecations;

public function testIsRegisteredThroughDirectiveAttribute(): void
{
$directive = new ToctreeDirective(new ToctreeBuilder(), new SettingsManager(new ProjectSettings()));

self::assertSame('toctree', $directive->getName());
self::assertTrue($directive->isUpgraded());
}

public function testCreatesTocNodeFromParserData(): void
{
$caption = InlineCompoundNode::getPlainTextInlineNode('Documentation');
$directive = new Directive('', 'toctree', '', [
'caption' => new DirectiveOption('caption', 'Documentation'),
'depth' => new DirectiveOption('depth', '2'),
'glob' => new DirectiveOption('glob', true),
'hidden' => new DirectiveOption('hidden', true),
'reversed' => new DirectiveOption('reversed', true),
'titlesonly' => new DirectiveOption('titlesonly', true),
'globExclude' => new DirectiveOption('globExclude', 'index,Index'),
]);
$directive->getOption('caption')->setNode($caption);

$directiveNode = new DirectiveNode($directive, rawContent: "guide/introduction\n guide/*\n");

$node = (new ToctreeDirective(new ToctreeBuilder(), new SettingsManager(new ProjectSettings())))
->createNode($directiveNode, self::createStub(CompilerContextInterface::class));

self::assertInstanceOf(TocNode::class, $node);
self::assertCount(2, $node->getMenuEntries());
self::assertSame(2, $node->getDepth());
self::assertTrue($node->isPageLevelOnly());
self::assertTrue($node->isReversed());
self::assertSame($caption, $node->getCaption());
self::assertSame('index,Index', $node->getOption('globExclude'));
self::assertTrue($node->hasOption('glob'));
self::assertTrue($node->hasOption('hidden'));
}

public function testUsesProjectIndexNameWhenGlobExcludeIsMissing(): void
{
$directiveNode = new DirectiveNode(new Directive('', 'toctree', ''), rawContent: '');

$node = (new ToctreeDirective(new ToctreeBuilder(), new SettingsManager(new ProjectSettings())))
->createNode($directiveNode, self::createStub(CompilerContextInterface::class));

self::assertInstanceOf(TocNode::class, $node);
self::assertSame('index,Index', $node->getOption('globExclude'));
}

#[WithoutErrorHandler]
public function testLegacyStartingRuleTriggersDeprecation(): void
{
$this->expectDeprecationWithIdentifier('https://github.com/phpDocumentor/guides/issues/1373');

new ToctreeDirective(new ToctreeBuilder(), self::createStub(Rule::class));
}

public function testSettingsManagerCanUseTheLegacyParameterPosition(): void
{
$this->expectNoDeprecationWithIdentifier('https://github.com/phpDocumentor/guides/issues/1373');

new ToctreeDirective(new ToctreeBuilder(), new SettingsManager(new ProjectSettings()));
}

#[WithoutErrorHandler]
public function testLegacyStartingRuleAndThirdSettingsManagerParameterRemainSupported(): void
{
$this->expectDeprecationWithIdentifier('https://github.com/phpDocumentor/guides/issues/1373');

new ToctreeDirective(
new ToctreeBuilder(),
self::createStub(Rule::class),
new SettingsManager(new ProjectSettings()),
);
}
}
6 changes: 0 additions & 6 deletions phpstan-baseline.neon
Original file line number Diff line number Diff line change
Expand Up @@ -282,12 +282,6 @@ parameters:
count: 1
path: packages/guides-restructured-text/src/RestructuredText/Directives/TitleDirective.php

-
message: '#^phpDocumentor\\Guides\\RestructuredText\\Directives\\ToctreeDirective should apply the attribute phpDocumentor\\Guides\\RestructuredText\\Directives\\Attributes\\Directive$#'
identifier: phpat.testConcreteDirectivesHaveTheDirectiveAttribute
count: 1
path: packages/guides-restructured-text/src/RestructuredText/Directives/ToctreeDirective.php

-
message: '#^Method phpDocumentor\\Guides\\RestructuredText\\Parser\\Productions\\DirectiveContentRule\:\:apply\(\) should return phpDocumentor\\Guides\\Nodes\\CollectionNode but returns phpDocumentor\\Guides\\Nodes\\CollectionNode\|TParent of phpDocumentor\\Guides\\Nodes\\CompoundNode\.$#'
identifier: return.type
Expand Down
Loading