Merge branch 'main' into bugfix/mdsections

Author: linawolf

.github/workflows/documentation.yml

@@ -37,4 +37,4 @@ jobs:
  dependency-versions: "highest"
 
  - name: "Run guides-cli"
- run: "vendor/bin/guides -vvv --no-progress docs --output='/tmp/test' --fail-on-log"
+ run: "vendor/bin/guides -vvv --no-progress docs --output='/tmp/test' --fail-on-error"

Makefile

@@ -47,8 +47,8 @@ test-xml: ## Lint all guides.xml
 ./tools/xmllint.sh
 
 .PHONY: test-docs
-test-docs: ## Generate projects docs without warnings
-$(PHP_BIN) vendor/bin/guides -vvv --no-progress docs --output="/tmp/test" --fail-on-log
+test-docs: ## Generate projects docs without errors
+$(PHP_BIN) vendor/bin/guides -vvv --no-progress docs --output="/tmp/test" --fail-on-error
 
 .PHONY: cleanup
 cleanup: cleanup-tests cleanup-build cleanup-cache

docs/_uml/application-flow.puml

@@ -0,0 +1,9 @@
+@startuml
+
+start
+:Parser;
+:Compiler;
+:render;
+stop
+
+@enduml

docs/about.rst

@@ -0,0 +1,51 @@
+============
+Architecture
+============
+
+The project is built around the core library that is called ``guides``. This library
+contains all core components of the project. Like the different layers :ref:`parser-component`,
+:ref:`compiler-component` and :ref:`renderer-component` and includes the basic Nodes and templates to create
+output.
+
+Installation of the core library can be done using ``composer``:
+
+.. code-block:: bash
+
+ composer require phpdocumentor/guides
+
+The other components are using the core library and extend it with additional
+functionality. For example the ``guides-markdown`` component adds support for
+Markdown documents and the ``guides-restructuredtext`` component adds support for
+ReStructuredText documents.
+
+All components are designed to be open for extension so you can bring your own parser,
+template engine or other component. The core library is designed to be the glue between
+all components.
+
+The ``guides``, ``guides-markdown`` and ``guides-restructuredtext`` are seen as the main
+libaries of the project. The other components are optional and can be used to extend the
+functionality of the main libraries for specific use cases.
+
+Application flow
+================
+
+Processing documents is done in a few steps.
+
+#. :php:class:`Parsing <\phpDocumentor\Guides\Parser>` The first step is to parse the document.
+ This is done by the :ref:`parser-component` component. The
+ parser component will parse the document and create a tree of nodes. Each node
+ represents a part of the document. For example a paragraph, a list or a table.
+#. :php:class:`Compiling <\phpDocumentor\Guides\Compiler\Compiler>` The second step is to compile the tree of nodes.
+ This is done by the :ref:`compiler-component`
+ component. During the compilation, modifications can be made to the tree of nodes. For
+ example the compiler can add a table of contents to the tree of nodes.
+
+#. :php:class:`Rendering <\phpDocumentor\Guides\Renderer\BaseTypeRenderer>` The third step is to render
+ the tree of nodes. This is done by the :ref:`renderer-component`
+ component. The render component will render the tree of nodes to a specific output
+ format. By default twig templates are used to render nodes to HTML. But you can
+ create your own templates to render nodes to other formats. Or implement your own
+ renderer to use a different template engine.
+
+.. uml:: _uml/application-flow.puml
+ :caption: Application flow

docs/architecture.rst

@@ -0,0 +1,10 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+ input="docs"
+ output="build/docs"
+ input-format="rst"
+>
+ <project title="phpDocumentor Guides"/>
+</guides>

docs/cli/basic-config.xml

@@ -0,0 +1,41 @@
+.. include:: /include.rst.txt
+
+=============
+Configuration
+=============
+
+The cli tool is able to read configuration from a ``guides.xml`` file.
+You should put this file in the current working directory where you execute
+the tool. Generally speaking, this is the root of your project.
+
+Using a configuration file allows you to set project-specific settings and
+keep them under version control. Not all options available in the configuration
+are available on the command line. Such as the :ref:`extension configuration`.
+
+.. note::
+
+ The ``guides.xml`` file is not required. If it is not present, the tool
+ will use the default configuration.
+
+Global configuration
+====================
+
+Settings that you want to have regardless of the documentation you are
+building should live in ``guides.xml`` in the current working directory.
+
+.. literalinclude:: ./basic-config.xml
+ :language: xml
+
+See the ``guides.xsd`` file for all available config options.
+
+Extension configuration
+=======================
+
+Some extensions allow extra configuration to be added to the ``guides.xml``
+
+.. literalinclude:: ./extension-config.xml
+ :language: xml
+
+.. hint::
+
+ If you want to learn more about the extensions, see the :doc:`/developers/extensions/index` documentation.

docs/cli/configuration.rst

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8" ?>
+<guides xmlns="https://www.phpdoc.org/guides"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="https://www.phpdoc.org/guides vendor/phpdocumentor/guides-cli/resources/schema/guides.xsd"
+
+ html-theme="bootstrap"
+>
+ <extension class="phpDocumentor\Guides\Bootstrap" />
+ <extension class="phpDocumentor\Guides\Code">
+ <language name="php" />
+ </extension>
+</guides>

docs/cli/extension-config.xml

@@ -0,0 +1,54 @@
+.. include:: /include.rst.txt
+
+================
+Getting started
+================
+
+This section describes how to use the commandline tool and how to configure it.
+The commandline tool is a small wrapper around the core library and can be used
+to render RST and Markdown files to HTML.
+
+Create your first documentation
+===============================
+
+After :doc:`/installation` you can directly start to create your first documentation.
+to do this, create a new directory named ``docs`` and create a file called ``index.rst`` in it.
+
+.. code-block:: rst
+
+ My first documentation
+ ======================
+
+ This is my first documentation. It is written in reStructuredText.
+
+ .. toctree::
+ :maxdepth: 2
+
+ chapter1
+ chapter2
+
+Now run the command to render the documentation:
+
+.. code-block:: bash
+
+ $ ./vendor/bin/guides docs
+
+You will find the output in the ``output`` directory and it should look like this:
+
+.. image:: first-docs.png
+ :alt: Example index file rendered to HTML
+
+Now you can start to write your documentation or read the :doc:`./configuration` section
+to learn more about the configuration.
+
+.. toctree::
+ :hidden:
+
+ configuration
+
+Extending
+=========
+
+Like any other component in this repository, the commandline tool can be extended. This can
+be done using an extension class, and referencing this class in the configuration file, like
+shown for in the :ref:`.extension-configuration` section.