[DOCS] Restructure docs

Author: jaapio

docs/architecture.rst

@@ -2,16 +2,15 @@
 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.
+The project is build around the core library that is called ``guides``. This library
+contains all core components of the project. Like the different layers :doc:`parser`,
+:doc:`compiler` and :doc:`render` and includes the basic Nodes and templates to create
+output.
 
-Installation of the core library can be done using ``composer``:
+Installation of the core library can be done using ``composer``::
 
-..  code-block:: bash
-
-    composer require phpdocumentor/guides
+.. code:: 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
@@ -25,27 +24,3 @@ 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`. 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/cli/configuration.rst

@@ -8,7 +8,7 @@ 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
+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`.
 

docs/cli/index.rst

@@ -12,7 +12,7 @@ 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.
+to do this create a new directory named ``docs`` and create a file called ``index.rst`` in it.
 
 .. code-block:: rst
 
@@ -49,6 +49,6 @@ to learn more about the 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
+Like any other component in this repository the commandline tool can be extended. This can
+be done using an extension class. And reference this class in the configuration file. Like
 shown for in the :ref:`.extension-configuration` section.

docs/developers/extensions/index.rst

@@ -1,7 +1,5 @@
 ..  include:: /include.rst.txt
 
-.. _developer-extension:
-
 ==========
 Extensions
 ==========

docs/developers/index.rst

@@ -8,9 +8,5 @@ application to render ReStructuredText or Markdown documents. Or want to integra
 it in some other way that is not possible with the ``guides`` command line tool.
 
 .. toctree::
-   :maxdepth: 1
-   :titlesonly:
 
    extensions/index
-   compiler
-   directive

docs/index.rst

@@ -18,17 +18,17 @@ Report issues
 Latest public documentation
     |composer_support_docs|
 
-If you are building your own application you can install the libraries using `Composer <https://getcomposer.org/>`__::
+This project contains a framework for rendering documentation. It provides a simple commandline tool to render
+your documentation from `reStructuredText Markup <https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html>`__ and
+`Markdown <https://daringfireball.net/projects/markdown/>`__. to HTML or LaTeX. And can be extended to support other
+formats.
 
-.. code:: bash
+Besides the commandline tool it also provides a number of libraries that can be used to build your own application
+to render the supported formats. To any format you want. On these pages is explained how to use the commandline tool
+and how to use the libraries.
 
-    composer require phpdocumentor/guides
-
-This will install all basic libraries needed to get started to get started.
-All libraries come with support for `Symfony dependency injection <https://symfony.com/doc/current/components/dependency_injection.html>`__.
-This will help you to get started with the libraries in symfony applications.
-
-Read more about writing your own application in the :doc:`developers` section.
+If you are looking for a complete solution to create a documentation website then you may want to look at
+`PHPDocumentor <https://phpdoc.org/>`__.
 
 .. tip::
 
@@ -44,8 +44,9 @@ Read more about writing your own application in the :doc:`developers` section.
 .. toctree::
     :hidden:
 
-    usage
-    configuration
-    extension/index
-    rst-reference/index
+    installation
+    cli/index
+    developers/index
+    architecture
+    reference/index
     about

docs/installation.rst

@@ -27,11 +27,11 @@ This will install the commandline tool in the vendor/bin directory. You can then
 
     vendor/bin/guides ./docs
 
-The commandline tool is built for extension, if you do not have special needs this is the
+The commandline tool is build for extension, if you do not have special needs this is the
 recommended way to get started. You can learn more about how to extend the commandline tool in the :doc:`/cli/index` section.
 
 Library (advanced)
-==================
+===============================
 
 .. _library:
 

docs/reference/restructuredtext/admonitions.rst

@@ -1,21 +1,86 @@
 ..  include:: /include.rst.txt
 
-.. _directive-reference:
-
 ===========
 Admonitions
 ===========
 
-Admonitions are blocks of text that are rendered in a special way to draw attention to them. They are often used to
-provide additional information to the reader about the content that is being discussed.
+The following directives are called "admonitions". You
+can use them to point out additional or important
+information.
+
+Examples
+========
+
+..  index:: reST directives; seealso
+
+See also
+--------
+
+..  code-block:: rest
+
+    ..  seealso::
+        `Admonitions <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__
+
+..  seealso::
+    `Admonitions <http://docutils.sourceforge.net/0.7/docs/ref/rst/directives.html#admonitions>`__
+
+
+..  index:: reST directives; note
+
+Note
+----
+
+..  code-block:: rest
+
+    ..  note::
+        A note
+
+..  note::
+    A note
+
+
+..  index:: reST directives; tip
+
+Tip
+---
+
+..  code-block:: rest
+
+    ..  tip::
+        A tip
+
+..  tip::
+    A tip
+
+You may also use the admonition **hint**, but this is very similar
+and **tip** is more commonly used in the documentation.
+
+..  index:: reST directives; warning
+
+Warning
+-------
+
+..  code-block:: rest
+
+    ..  warning::
+        Some text pointing out something that people should be warned about.
+
+..  warning::
+    Some text pointing out something that people should be warned about.
+
+You may also use the admonitions **caution** or even **danger** if the
+severity of the warning must be stressed.
+
+
+..  index:: reST directives; attention
 
-.. index:: reST directives; seealso
+Attention
+---------
 
-.. phpdoc:class-list:: [?(@.inheritedElement == "\phpDocumentor\Guides\RestructuredText\Directives\AbstractAdmonitionDirective")]
+..  code-block:: rest
 
-   .. phpdoc:name::
-      :title: true
-      :level: 2
+    ..  attention::
+        A attention
 
-   .. phpdoc:summary::
-   .. phpdoc:description::
+..  attention::
+    A attention