[FEATURE] Make relative, absolute and links relative to a base URL possible

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

@@ -4,6 +4,7 @@
 
 use phpDocumentor\Guides\Graphs\Directives\UmlDirective;
 use phpDocumentor\Guides\NodeRenderers\NodeRenderer;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Directives\AdmonitionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\AttentionDirective;
 use phpDocumentor\Guides\RestructuredText\Directives\BaseDirective;
@@ -106,7 +107,6 @@
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
 use phpDocumentor\Guides\RestructuredText\Toc\GlobSearcher;
 use phpDocumentor\Guides\RestructuredText\Toc\ToctreeBuilder;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 use Psr\Log\LoggerInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 
@@ -166,7 +166,7 @@
         ])
         ->set(ContainerDirective::class)
         ->set(ContentsDirective::class)
-        ->arg('$urlGenerator', service(UrlGeneratorInterface::class))
+        ->arg('$documentNameResolver', service(DocumentNameResolverInterface::class))
         ->set(CsvTableDirective::class)
         ->arg('$productions', service('phpdoc.guides.parser.rst.body_elements'))
         ->set(DangerDirective::class)

packages/guides-restructured-text/src/RestructuredText/Directives/ContentsDirective.php

@@ -6,9 +6,9 @@
 
 use phpDocumentor\Guides\Nodes\Menu\ContentMenuNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 
 /**
  * Standarad rst `contents` directive
@@ -17,8 +17,9 @@
  */
 class ContentsDirective extends BaseDirective
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     public function getName(): string
@@ -32,7 +33,7 @@ public function process(
         Directive $directive,
     ): Node|null {
         $options = $directive->getOptions();
-        $absoluteUrl = $this->urlGenerator->absoluteUrl(
+        $absoluteUrl = $this->documentNameResolver->absoluteUrl(
             $blockContext->getDocumentParserContext()->getContext()->getDirName(),
             $blockContext->getDocumentParserContext()->getContext()->getCurrentFileName(),
         );

packages/guides-restructured-text/src/RestructuredText/Directives/ImageDirective.php

@@ -6,9 +6,9 @@
 
 use phpDocumentor\Guides\Nodes\ImageNode;
 use phpDocumentor\Guides\Nodes\Node;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\Directive;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 
 use function dirname;
 
@@ -21,8 +21,9 @@
  */
 class ImageDirective extends BaseDirective
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     public function getName(): string
@@ -36,7 +37,7 @@ public function processNode(
         Directive $directive,
     ): Node {
         return new ImageNode(
-            $this->urlGenerator->absoluteUrl(
+            $this->documentNameResolver->absoluteUrl(
                 dirname($blockContext->getDocumentParserContext()->getContext()->getCurrentAbsolutePath()),
                 $directive->getData(),
             ),

packages/guides-restructured-text/src/RestructuredText/Toc/GlobSearcher.php

@@ -6,14 +6,15 @@
 
 use Flyfinder\Specification\Glob;
 use phpDocumentor\Guides\ParserContext;
-use phpDocumentor\Guides\UrlGeneratorInterface;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 
 use function rtrim;
 
 class GlobSearcher
 {
-    public function __construct(private readonly UrlGeneratorInterface $urlGenerator)
-    {
+    public function __construct(
+        private readonly DocumentNameResolverInterface $documentNameResolver,
+    ) {
     }
 
     /** @return string[] */
@@ -25,7 +26,7 @@ public function globSearch(ParserContext $parserContext, string $globPattern): a
         );
         $allFiles = [];
         foreach ($files as $file) {
-            $allFiles[] = $this->urlGenerator->absoluteUrl($parserContext->getDirName(), $file['filename']);
+            $allFiles[] = $this->documentNameResolver->absoluteUrl($parserContext->getDirName(), $file['filename']);
         }
 
         return $allFiles;

packages/guides-restructured-text/tests/unit/Parser/Productions/RuleTestCase.php

@@ -9,13 +9,13 @@
 use phpDocumentor\Guides\Nodes\InlineCompoundNode;
 use phpDocumentor\Guides\Nodes\ProjectNode;
 use phpDocumentor\Guides\ParserContext;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolver;
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
 use phpDocumentor\Guides\RestructuredText\Parser\LinesIterator;
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
-use phpDocumentor\Guides\UrlGenerator;
 use PHPUnit\Framework\TestCase;
 
 abstract class RuleTestCase extends TestCase
@@ -41,7 +41,7 @@ protected function createContext(string $input): BlockContext
             'test',
             1,
             self::createStub(FilesystemInterface::class),
-            new UrlGenerator(),
+            new DocumentNameResolver(),
         );
         $documentParserContext = new DocumentParserContext(
             $parserContext,

packages/guides-restructured-text/tests/unit/Parser/Productions/SectionRuleTest.php

@@ -20,12 +20,12 @@
 use phpDocumentor\Guides\Nodes\SectionNode;
 use phpDocumentor\Guides\Nodes\TitleNode;
 use phpDocumentor\Guides\ParserContext;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\RestructuredText\MarkupLanguageParser;
 use phpDocumentor\Guides\RestructuredText\Parser\BlockContext;
 use phpDocumentor\Guides\RestructuredText\Parser\DocumentParserContext;
 use phpDocumentor\Guides\RestructuredText\Parser\InlineParser;
 use phpDocumentor\Guides\RestructuredText\TextRoles\TextRoleFactory;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 
 final class SectionRuleTest extends RuleTestCase
 {
@@ -196,7 +196,7 @@ private function getDocumentParserContext(string $content): BlockContext
             'test',
             1,
             self::createStub(FilesystemInterface::class),
-            self::createStub(UrlGeneratorInterface::class),
+            self::createStub(DocumentNameResolverInterface::class),
         );
 
         $documentParserContext = new DocumentParserContext(

packages/guides/resources/config/guides.php

@@ -27,6 +27,8 @@
 use phpDocumentor\Guides\ReferenceResolvers\AnchorReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\DelegatingReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\DocReferenceResolver;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolver;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use phpDocumentor\Guides\ReferenceResolvers\EmailReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\ExternalReferenceResolver;
 use phpDocumentor\Guides\ReferenceResolvers\InternalReferenceResolver;
@@ -39,14 +41,17 @@
 use phpDocumentor\Guides\Renderer\IntersphinxRenderer;
 use phpDocumentor\Guides\Renderer\LatexRenderer;
 use phpDocumentor\Guides\Renderer\TypeRendererFactory;
+use phpDocumentor\Guides\Renderer\UrlGenerator\AbsoluteUrlGenerator;
+use phpDocumentor\Guides\Renderer\UrlGenerator\AbstractUrlGenerator;
+use phpDocumentor\Guides\Renderer\UrlGenerator\ConfigurableUrlGenerator;
+use phpDocumentor\Guides\Renderer\UrlGenerator\RelativeUrlGenerator;
+use phpDocumentor\Guides\Renderer\UrlGenerator\UrlGeneratorInterface;
 use phpDocumentor\Guides\Settings\SettingsManager;
 use phpDocumentor\Guides\TemplateRenderer;
 use phpDocumentor\Guides\Twig\AssetsExtension;
 use phpDocumentor\Guides\Twig\EnvironmentBuilder;
 use phpDocumentor\Guides\Twig\Theme\ThemeManager;
 use phpDocumentor\Guides\Twig\TwigTemplateRenderer;
-use phpDocumentor\Guides\UrlGenerator;
-use phpDocumentor\Guides\UrlGeneratorInterface;
 use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
 use Symfony\Component\DependencyInjection\Reference;
 use Symfony\Component\HttpClient\HttpClient;
@@ -93,7 +98,10 @@
             '%vendor_dir%/phpdocumentor/guides/src/NodeRenderers',
         )
 
-        ->set(UrlGeneratorInterface::class, UrlGenerator::class)
+        ->set(AbsoluteUrlGenerator::class)
+        ->set(RelativeUrlGenerator::class)
+        ->set(UrlGeneratorInterface::class, ConfigurableUrlGenerator::class)
+        ->set(DocumentNameResolverInterface::class, DocumentNameResolver::class)
 
         ->set(Parser::class)
         ->arg('$parserStrategies', tagged_iterator('phpdoc.guides.parser.markupLanguageParser'))
@@ -118,7 +126,7 @@
         ->set(HttpClientInterface::class)
         ->factory([HttpClient::class, 'create'])
 
-        ->set(UrlGenerator::class)
+        ->set(AbstractUrlGenerator::class)
 
         ->set(ExternalReferenceResolver::class)
 

packages/guides/resources/template/html/body/menu/menu.html.twig

@@ -1,5 +1,3 @@
-{% apply spaceless %}
-    <div class="menu">
-        {% include "body/menu/menu-level.html.twig" %}
-    </div>
-{% endapply %}
+<div class="menu">
+    {% include "body/menu/menu-level.html.twig" %}
+</div>

packages/guides/resources/template/tex/inline/inline-node.tex.twig

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

packages/guides/resources/template/tex/inline/plain-text.tex.twig

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

packages/guides/resources/template/tex/structure/header-title.tex.twig

@@ -0,0 +1,6 @@
+{%- apply spaceless -%}
+{%- set headingLevel = node.level -%}
+\{% if headingLevel == 1 %}section{% elseif headingLevel == 2 %}subsection{% elseif headingLevel == 3 %}subsubsection{% elseif headingLevel == 4 %}paragraph{% elseif headingLevel == 5 %}subparagraph{% elseif headingLevel == 6 %}subparagraph{% endif %}{
+{{- renderNode(node.value) -}}
+}
+{%- endapply -%}

packages/guides/resources/template/tex/structure/section.tex.twig

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

packages/guides/src/DependencyInjection/GuidesExtension.php

@@ -70,6 +70,7 @@ public function getConfigTreeBuilder(): TreeBuilder
                 ->scalarNode('log_path')->end()
                 ->scalarNode('fail_on_log')->end()
                 ->scalarNode('show_progress')->end()
+                ->scalarNode('links_are_relative')->end()
                 ->arrayNode('base_template_paths')
                     ->defaultValue([])
                     ->scalarPrototype()->end()
@@ -152,6 +153,10 @@ public function load(array $configs, ContainerBuilder $container): void
             $projectSettings->setOutputFormats($config['output_format']);
         }
 
+        if (isset($config['links_are_relative'])) {
+            $projectSettings->setLinksRelative((bool) $config['links_are_relative']);
+        }
+
         if (isset($config['show_progress'])) {
             $projectSettings->setShowProgressBar((bool) $config['show_progress']);
         }

packages/guides/src/Nodes/Menu/MenuEntryNode.php

@@ -33,6 +33,11 @@ public function getUrl(): string
         return $this->url;
     }
 
+    public function getDocumentLink(): string
+    {
+        return '/' . $this->url;
+    }
+
     public function getAnchor(): string
     {
         return $this->anchor;

packages/guides/src/Parser.php

@@ -18,6 +18,7 @@
 use League\Flysystem\FilesystemInterface;
 use phpDocumentor\Guides\Nodes\DocumentNode;
 use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 use RuntimeException;
 use Webmozart\Assert\Assert;
 
@@ -36,7 +37,7 @@ final class Parser
 
     /** @param iterable<MarkupLanguageParser> $parserStrategies */
     public function __construct(
-        private readonly UrlGeneratorInterface $urlGenerator,
+        private readonly DocumentNameResolverInterface $documentNameResolver,
         iterable $parserStrategies,
     ) {
         foreach ($parserStrategies as $strategy) {
@@ -118,7 +119,7 @@ private function createParserContext(
             $sourcePath,
             $initialHeaderLevel,
             $origin,
-            $this->urlGenerator,
+            $this->documentNameResolver,
         );
     }
 }

packages/guides/src/ParserContext.php

@@ -8,6 +8,7 @@
 use League\Uri\Uri;
 use League\Uri\UriInfo;
 use phpDocumentor\Guides\Nodes\ProjectNode;
+use phpDocumentor\Guides\ReferenceResolvers\DocumentNameResolverInterface;
 
 use function dirname;
 use function ltrim;
@@ -20,7 +21,7 @@ public function __construct(
         private readonly string $currentDirectory,
         private readonly int $initialHeaderLevel,
         private readonly FilesystemInterface $origin,
-        private readonly UrlGeneratorInterface $urlGenerator,
+        private readonly DocumentNameResolverInterface $documentNameResolver,
     ) {
     }
 
@@ -94,6 +95,6 @@ public function getUrl(): string
      */
     public function getCurrentAbsolutePath(): string
     {
-        return $this->urlGenerator->absoluteUrl($this->currentDirectory, $this->currentFileName);
+        return $this->documentNameResolver->absoluteUrl($this->currentDirectory, $this->currentFileName);
     }
 }

packages/guides/src/UrlGenerator.php → packages/guides/src/ReferenceResolvers/DocumentNameResolver.php

@@ -11,18 +11,18 @@
  * @link https://phpdoc.org
  */
 
-namespace phpDocumentor\Guides;
+namespace phpDocumentor\Guides\ReferenceResolvers;
 
 use League\Uri\UriInfo;
+use phpDocumentor\Guides\UriFactory;
 
 use function array_pop;
 use function explode;
 use function implode;
 use function ltrim;
-use function rtrim;
 use function trim;
 
-final class UrlGenerator implements UrlGeneratorInterface
+final class DocumentNameResolver implements DocumentNameResolverInterface
 {
     /**
      * Returns the absolute path, including prefixing '/'.
@@ -33,6 +33,7 @@ final class UrlGenerator implements UrlGeneratorInterface
     public function absoluteUrl(string $basePath, string $url): string
     {
         $uri = UriFactory::createUri($url);
+
         if (UriInfo::isAbsolute($uri)) {
             return $url;
         }
@@ -81,34 +82,4 @@ public function canonicalUrl(string $basePath, string $url): string
 
         return ltrim(implode('/', $dirNameParts) . '/' . implode('/', $urlPass1), '/');
     }
-
-    public function createFileUrl(string $filename, string $outputFormat = 'html', string|null $anchor = null): string
-    {
-        return $filename . '.' . $outputFormat .
-            ($anchor !== null ? '#' . $anchor : '');
-    }
-
-    /**
-     * Generate a canonical output URL with file extension, anchor and prefixed by
-     * an absolute or relative path
-     */
-    public function generateOutputUrlFromDocumentPath(
-        string $currentDirectory,
-        string $destinationPath,
-        string $linkedDocument,
-        string $outputFormat,
-        string|null $anchor = null,
-    ): string {
-        $canonicalUrl = $this->canonicalUrl(
-            $currentDirectory,
-            $linkedDocument,
-        );
-
-        $fileUrl = $this->createFileUrl($canonicalUrl, $outputFormat, $anchor);
-        if ($destinationPath === '') {
-            return $fileUrl;
-        }
-
-        return rtrim($destinationPath, '/') . '/' . $fileUrl;
-    }
 }