Allow multiple docs contexts (for example: including legacy versions)

composer.json

@@ -40,6 +40,9 @@
         "symfony/phpunit-bridge": "^4.4|^5.1",
         "symplify/easy-coding-standard": "^9.0"
     },
+    "conflict": {
+        "symplify/easy-coding-standard": "9.3.*"
+    },
     "config": {
         "preferred-install": "dist",
         "sort-packages": true

docs/how-to-add-docs-contexts.md

@@ -0,0 +1,34 @@
+# How to add docs contexts
+
+You can add several contexts of the documentation.
+
+For example, you can add a context to browse the legacy versions of your documentation.
+
+```yaml
+# config/packages/mobizel_markdown_docs.yaml
+
+mobizel_markdown_docs:
+    contexts:
+        legacy:
+            path: /{version}
+            docs_dir: '/path/to/your/legacy_docs/{versions}'
+            requirements:
+                version: '(\d+)\.(\d+)'
+```
+
+Another example is to add a context for your packages.
+
+```yaml
+mobizel_markdown_docs:
+    contexts:
+        packages:
+            path: /packages/{package}/{version}
+            docs_dir: '/path/to/your/packages_docs/{package}/{version}'
+            requirements:
+                package: '.+'
+                version: '(\d+)\.(\d+)'
+```
+
+`Warning`
+Remember the first context to match the route path will be used.
+So the order of your contexts can be important.

docs/how-to-use.md

@@ -2,13 +2,16 @@
 
 Markdown templates are on `docs` directory.
 
-You can customize the docs directory: 
+You can customize your main docs directory: 
 
 ```yaml
 # config/packages/mobizel_markdown_docs.yaml
 
 mobizel_markdown_docs:
-    docs_dir: '/path/to/your/docs'
+    contexts:
+        main:
+            path: /docs
+            docs_dir: '/path/to/your/docs'
 ```
 
 Your files are already available on your server.

docs/index.md

@@ -2,5 +2,6 @@
 
 * [Setup](setup.md)
 * [How to use](how-to-use.md)
+* [How to add docs contexts](how-to-add-docs-contexts.md)
 * [How to add warning and notes](how-to-add-warning-and-notes.md)
 * [How to draw charts](how-to-draw-charts)

docs/setup.md

@@ -5,9 +5,12 @@ composer config extra.symfony.allow-contrib true
 composer require mobizel/markdown-docs-bundle
 ```
 
-If you don't use Symfony Flex, add the required routes on `config/routes.yaml`: 
+If you don't use Symfony Flex, add the required configuration on `config/packages/mobizel_markdown_docs.yaml`: 
 
 ```yaml
-_mobizel_markdowns:
-    resource: '@MobizelMarkdownDocsBundle/Resources/config/routes.xml'
+mobizel_markdown_docs:
+    contexts:
+        main:
+            path: /docs
+            docs_dir: '%kernel.project_dir%/docs'
 ```

spec/DataProvider/PageCollectionDataProviderSpec.php

@@ -2,33 +2,48 @@
 
 namespace spec\Mobizel\Bundle\MarkdownDocsBundle\DataProvider;
 
+use Mobizel\Bundle\MarkdownDocsBundle\Context\ReaderContextInterface;
 use Mobizel\Bundle\MarkdownDocsBundle\DataProvider\PageCollectionDataProvider;
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextInterface;
 use PhpSpec\ObjectBehavior;
+use Symfony\Component\HttpFoundation\Request;
+use Symfony\Component\HttpFoundation\RequestStack;
 
 class PageCollectionDataProviderSpec extends ObjectBehavior
 {
-    function let(): void
+    function let(ReaderContextInterface $readerContext, RequestStack $requestStack, Request $request): void
     {
-        $docsDir =  realpath(dirname(__FILE__).'/../../tests/docs');
-
-        $this->beConstructedWith($docsDir);
+        $requestStack->getCurrentRequest()->willReturn($request);
+        $this->beConstructedWith($readerContext, $requestStack);
     }
 
     function it_is_initializable(): void
     {
         $this->shouldHaveType(PageCollectionDataProvider::class);
     }
 
-    function it_returns_root_pages(): void
-    {
+    function it_returns_root_pages(
+        ReaderContextInterface $readerContext,
+        ContextInterface $context,
+        Request $request
+    ): void {
+        $readerContext->getContext()->willReturn($context);
+        $context->getDocsDir($request)->willReturn(realpath(dirname(__FILE__).'/../../tests/docs'));
+
         $rootPages = $this->getRootPages();
         $rootPages->shouldHaveCount(7);
         $rootPages[0]->slug->shouldReturn('index');
         $rootPages[0]->title->shouldReturn('Documentation');
     }
 
-    function it_returns_children_pages(): void
-    {
+    function it_returns_children_pages(
+        ReaderContextInterface $readerContext,
+        ContextInterface $context,
+        Request $request
+    ): void {
+        $readerContext->getContext()->willReturn($context);
+        $context->getDocsDir($request)->willReturn(realpath(dirname(__FILE__).'/../../tests/docs'));
+
         $childrenPages = $this->getChildrenPages('products');
         $childrenPages->shouldHaveCount(2);
         $childrenPages[0]->slug->shouldReturn('products/board-games');
@@ -37,8 +52,14 @@ function it_returns_children_pages(): void
         $childrenPages[1]->title->shouldReturn('Book homepage');
     }
 
-    function it_returns_pages_map(): void
-    {
+    function it_returns_pages_map(
+        ReaderContextInterface $readerContext,
+        ContextInterface $context,
+        Request $request
+    ): void {
+        $readerContext->getContext()->willReturn($context);
+        $context->getDocsDir($request)->willReturn(realpath(dirname(__FILE__).'/../../tests/docs'));
+
         $this->getPagesMap()->shouldReturn([
             'index' => 'Documentation',
             'bar' => 'Bar',
@@ -57,8 +78,14 @@ function it_returns_pages_map(): void
         ]);
     }
 
-    function it_returns_pases_as_tree(): void
-    {
+    function it_returns_pages_as_tree(
+        ReaderContextInterface $readerContext,
+        ContextInterface $context,
+        Request $request
+    ): void {
+        $readerContext->getContext()->willReturn($context);
+        $context->getDocsDir($request)->willReturn(realpath(dirname(__FILE__).'/../../tests/docs'));
+
         $tree = $this->getPagesAsTree();
 
         $tree->shouldHaveCount(7);

spec/Docs/ContextRegistrySpec.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace spec\Mobizel\Bundle\MarkdownDocsBundle\Docs;
+
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextInterface;
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextRegistry;
+use PhpSpec\ObjectBehavior;
+
+class ContextRegistrySpec extends ObjectBehavior
+{
+    function let(ContextInterface $firstContext, ContextInterface $secondContext): void
+    {
+        $firstContext->getName()->willReturn('first');
+        $secondContext->getName()->willReturn('second');
+        $this->beConstructedWith([$firstContext, $secondContext]);
+    }
+
+    function it_is_initializable(): void
+    {
+        $this->shouldHaveType(ContextRegistry::class);
+    }
+
+    function it_adds_contexts(ContextInterface $context): void
+    {
+        $context->getName()->willReturn('third');
+
+        $this->add($context);
+
+        $this->getAll()->shouldContain($context);
+        $this->getAll()->shouldHaveCount(3);
+    }
+
+    function it_returns_all_contexts(ContextInterface $firstContext, ContextInterface $secondContext): void
+    {
+        $this->getAll()->shouldContain($firstContext);
+        $this->getAll()->shouldContain($secondContext);
+    }
+}

spec/Docs/ContextResolverSpec.php

@@ -0,0 +1,45 @@
+<?php
+
+namespace spec\Mobizel\Bundle\MarkdownDocsBundle\Docs;
+
+use http\Client\Request;
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextInterface;
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextRegistryInterface;
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\ContextResolver;
+use PhpSpec\ObjectBehavior;
+
+class ContextResolverSpec extends ObjectBehavior
+{
+    function let(ContextRegistryInterface $contextRegistry): void
+    {
+        $this->beConstructedWith($contextRegistry);
+    }
+
+    function it_is_initializable(): void
+    {
+        $this->shouldHaveType(ContextResolver::class);
+    }
+
+    function it_does_not_returns_any_context_when_registry_is_empty(
+        ContextRegistryInterface $contextRegistry
+    ): void {
+        $contextRegistry->getAll()->willReturn([]);
+
+        $this->resolve('/docs')->shouldReturn(null);
+    }
+
+    function it_resolves_the_path_to_return_the_right_context(
+        ContextRegistryInterface $contextRegistry,
+        ContextInterface $currentVersionContext,
+        ContextInterface $legacyVersionContext
+    ): void {
+        $contextRegistry->getAll()->willReturn([$currentVersionContext->getWrappedObject(), $legacyVersionContext->getWrappedObject()]);
+        $currentVersionContext->getPath()->willReturn('/current');
+        $currentVersionContext->getPattern()->willReturn('/\/current/');
+        $legacyVersionContext->getPath()->willReturn('/{version}');
+        $legacyVersionContext->getPattern()->willReturn('/(\d+).(\d+)/');
+
+        $this->resolve('/current/setup/requirements')->shouldReturn($currentVersionContext);
+        $this->resolve('/1.2/setup/requirements')->shouldReturn($legacyVersionContext);
+    }
+}

spec/Docs/ContextSpec.php

@@ -0,0 +1,57 @@
+<?php
+
+namespace spec\Mobizel\Bundle\MarkdownDocsBundle\Docs;
+
+use Mobizel\Bundle\MarkdownDocsBundle\Docs\Context;
+use PhpSpec\ObjectBehavior;
+use Symfony\Component\HttpFoundation\Request;
+
+class ContextSpec extends ObjectBehavior
+{
+    function let(): void
+    {
+        $this->beConstructedWith('default', '/docs', './docs', []);
+    }
+
+    function it_is_initializable()
+    {
+        $this->shouldHaveType(Context::class);
+    }
+
+    public function it_can_get_path(): void
+    {
+        $this->getPath()->shouldReturn('/docs');
+    }
+
+    public function it_can_get_pattern(): void
+    {
+        $this->beConstructedWith('legacy', '/{project}/{version}', './legacy_docs/{project}/{version}', [
+            'project' => '(\w+)',
+            'version' => '(\d+).(\d+)'
+        ]);
+
+        $this->getPattern()->shouldReturn('/\/(\w+)\/(\d+).(\d+)/');
+    }
+
+    public function it_can_get_docs_dir(Request $request): void
+    {
+        $request->get('_route_params')->willReturn([]);
+
+        $this->getDocsDir($request)->shouldReturn('./docs');
+    }
+
+    public function it_replaces_params_in_docs_dir(Request $request): void
+    {
+        $this->beConstructedWith('legacy', '/{project}/{version}', './docs/{project}/{version}', [
+            'project' => '(\w+)',
+            'version' => '(\d+).(\d+)'
+        ]);
+
+        $request->get('_route_params')->willReturn([
+            'project' => 'my-project',
+            'version' => '1.2',
+        ]);
+
+        $this->getDocsDir($request)->shouldReturn('./docs/my-project/1.2');
+    }
+}

spec/Helper/PageHelperSpec.php

@@ -2,18 +2,21 @@
 
 namespace spec\Mobizel\Bundle\MarkdownDocsBundle\Helper;
 
+use Mobizel\Bundle\MarkdownDocsBundle\DataProvider\PageCollectionDataProviderInterface;
 use Mobizel\Bundle\MarkdownDocsBundle\Helper\PageHelper;
 use PhpSpec\ObjectBehavior;
 
 class PageHelperSpec extends ObjectBehavior
 {
-    function let(): void
+    function let(PageCollectionDataProviderInterface $pageCollectionDataProvider): void
     {
-        $this->beConstructedWith([
+        $pageCollectionDataProvider->getPagesMap()->willReturn([
             'first-page' => 'First page',
             'foo' => 'Foo fighters',
             'last-page' => 'Last page',
         ]);
+
+        $this->beConstructedWith($pageCollectionDataProvider);
     }
 
     function it_is_initializable(): void

spec/Page/PageInfoSpec.php

@@ -2,7 +2,6 @@
 
 namespace spec\Mobizel\Bundle\MarkdownDocsBundle\Page;
 
-use Mobizel\Bundle\MarkdownDocsBundle\Template\TemplateHandlerInterface;
 use PhpSpec\ObjectBehavior;
 
 class PageInfoSpec extends ObjectBehavior
@@ -13,14 +12,14 @@ function it_can_get_page_title(): void
         $this->getTitle()->shouldReturn('Foo fighters');
     }
 
-    function it_return_default_title_when_no_title_has_been_found(TemplateHandlerInterface $templateHandler): void
+    function it_return_default_title_when_no_title_has_been_found(): void
     {
         $this->beConstructedWith('tests/docs/bar.md', '', '');
 
         $this->getTitle()->shouldReturn('Bar');
     }
 
-    function it_return_default_title_when_file_is_empty(TemplateHandlerInterface $templateHandler): void
+    function it_return_default_title_when_file_is_empty(): void
     {
         $this->beConstructedWith('tests/docs/empty.md', '', '');