Merge pull request #473 from greg0ire/document-extension

 Document how to create an extension

Author: linawolf

docs/components/compiler.rst

@@ -8,22 +8,26 @@ This library uses a simplified compiler design. This basically means that our pi
 than a regular compiler. But its following the same semantics.
 
 Lexing and Parsing
+==================
 
-A typical compiler will have separate lexing, syntax analisys. However the parser
-was designed to do part of the lexing because of all context dependend logic of most Markup languages.
+A typical compiler will have separate lexing, syntax analysis. However the parser
+was designed to do part of the lexing because of all context-dependent logic of most Markup languages.
 We call this the parsing phase. This will result into an AST that is mostly close to the original source. It
 might contain some optimizations for later use.
 
 Semantic analysis and Intermediate code generation
+==================================================
 
 The semantic analysis phase of this library is performing a number of steps to collect information of the parsed markup
-language. An good example is the collection of the table of contents and the metadata of the parsed documents.
+language. A good example is the collection of the table of contents and the metadata of the parsed documents.
 This is the moment where document node traversers are executed.
 
 Code optimization
+=================
 
 Do some pre-rendering stuff, like buiding the TOC content and other rendering preparations before the real rendering starts.
 
 Code generation
+===============
 
-Code generation a.k. rendering. We do deliver a headless
+Code generation a.k.a. rendering. We do deliver a headless

docs/extension/index.rst

@@ -4,6 +4,28 @@
 Extending the phpdocumentor/guides
 ==================================
 
+``phpdocumentor/guides`` relies on `Symfony Dependency Injection
+Container
+<https://symfony.com/doc/current/components/dependency_injection.html#setting-up-the-container-with-configuration-files>`__
+extensions. This means that to extend the guides, you need to define
+such an extension, after what it becomes possible to make the guides CLI
+aware of it by creating a ``guides.xml`` file in the directory from
+which you invoke the CLI.
+
+It should look like this::
+
+.. code-block:: xml
+
+    <?xml version="1.0" encoding="UTF-8" ?>
+    <guides>
+        <extension class="YourName\YourExtension\DependencyInjection\YourExtension"/>
+    </guides>
+
+Internally, the guides CLI defines and uses default extensions.
+Once you have that set up, you can create PHP classes, define services
+from it, and tag them so that they are recognized and usable by the
+guides CLI.
+
 Some ways to extend the guides:
 
 .. toctree::

packages/guides-cli/src/DependencyInjection/ContainerFactory.php

@@ -97,12 +97,12 @@ private function resolveExtensionClass(string $name): string
 
             $fqcn = implode('\\', [$fqcn, 'DependencyInjection', $package . 'Extension']);
             if (!class_exists($fqcn)) {
-                throw new LogicException(sprintf('Extension "%s" does not exists.', $fqcn));
+                throw new LogicException(sprintf('Extension "%s" does not exist.', $fqcn));
             }
         }
 
         if (!is_a($fqcn, ExtensionInterface::class, true)) {
-            throw new LogicException(sprintf('Extension "%s" does not exists.', $fqcn));
+            throw new LogicException(sprintf('Extension "%s" does not exist.', $fqcn));
         }
 
         return $fqcn;

packages/guides-restructured-text/README.rst

@@ -23,7 +23,7 @@ This repository is part of `phpDocumentor's Guides library <https://github.com/p
 designed to take hand-written documentation in code repositories and create an AST (abstract syntax tree) from it.
 This AST is then fed to a renderer, which produces the desired output, such as HTML.
 
-The package `phpdocumentor/guides-markdown <https://packagist.org/packages/phpdocumentor/guides-restructured-text>`__ adds
+The package `phpdocumentor/guides-restructured-text <https://packagist.org/packages/phpdocumentor/guides-restructured-text>`__ adds
 `reStructuredText Markup <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`__ support to the
 phpDocumentor's Guides library.