Update documentation and a bit of styling

phpDocumentor · Mar 7, 2021 · fee60c5 · fee60c5
1 parent 26b852b
commit fee60c5
Show file tree

Hide file tree

Showing 17 changed files with 284 additions and 496 deletions.
diff --git a/data/templates/default/guides/toc-level.html.twig b/data/templates/default/guides/toc-level.html.twig
@@ -1,5 +1,5 @@
 {% spaceless %}
-    <ul>
+    <ul class="phpdocumentor-list">
         {% for tocItem in tocItems %}
             {% include "guides/toc-item.html.twig" %}
         {% endfor %}

diff --git a/data/templates/default/objects/headings.css.twig b/data/templates/default/objects/headings.css.twig
@@ -20,7 +20,6 @@
     font-size: var(--text-xxxl);
     letter-spacing: var(--letter-spacing--primary);
     line-height: 1.25;
-    margin-top: 0;
 }
 
 .phpdocumentor h3 {

diff --git a/data/templates/default/objects/lists.css.twig b/data/templates/default/objects/lists.css.twig
@@ -31,3 +31,11 @@ ol.phpdocumentor-list ul.phpdocumentor-list {
 li.phpdocumentor-list {
     margin-bottom: var(--spacing-md);
 }
+
+.phpdocumentor dl dt {
+    margin-bottom: var(--spacing-xs);
+}
+
+.phpdocumentor dl dd {
+    margin-bottom: var(--spacing-md);
+}
diff --git a/docs/getting-started/changing-the-look-and-feel.rst b/docs/getting-started/changing-the-look-and-feel.rst
diff --git a/docs/getting-started/creating-your-own-template-using-twig.rst b/docs/getting-started/creating-your-own-template-using-twig.rst
diff --git a/docs/getting-started/generating-documentation.rst b/docs/getting-started/generating-documentation.rst
@@ -0,0 +1,52 @@
+Generating documentation
+========================
+
+After you have :doc:`installed<installing>` phpDocumentor you can use the ``phpdoc`` command to generate
+your documentation.
+
+Throughout this documentation we expect that the ``phpdoc`` command is available; thus whenever we ask you
+to run a command, it will be in the following form
+
+.. code-block:: shell-session
+
+    $ phpdoc
+
+.. hint::
+
+    When you have installed a version via composer or manually you should invoke the ``phpdoc`` script in
+    the ``bin`` folder of your phpDocumentor installation.
+
+    Under Linux / MacOSX that would be
+
+    .. code-block:: shell-session
+
+        $ [PHPDOC_FOLDER]/bin/phpdoc
+
+    And under Windows that would be
+
+    .. code-block:: shell-session
+
+        $ [PHPDOC_FOLDER]\bin\phpdoc.bat
+
+The basic usage of phpDocumentor is to provide an input location using the command line options
+(``-d`` for a directory, ``-f`` for a file) and tell it to output your documentation to a folder of your
+liking (``-t``).
+
+For example:
+
+.. code-block:: shell-session
+
+    $ phpdoc -d ./src -t ./docs/api
+
+What the above example does, is scan all files in the ``src`` directory and its subdirectories, perform
+an analysis and generate a website containing the documentation in the folder ``docs/api``. If you want,
+you can omit the ``-t`` option, in which case the output will be written to a subfolder called ``output``.
+
+Read more
+~~~~~~~~~
+
+- :doc:`../references/configuration`, there are a lot more options to phpDocumentor. To maintain consistent
+  documentation, it is good practice to define them all in a :doc:`../references/configuration` file and to
+  include that in your project.
+- :doc:`../guides/running-phpdocumentor`, there are a ton more options you can add onto the command line; check
+  this out!
diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst
@@ -1,9 +1,14 @@
 Getting started
 ===============
 
+Is this the first time you work with phpDocumentor? You have come to the right section in the documentation! In the
+chapters included of this section we will talk you through the installation, configuration and how to generate your
+documentation.
+
 .. toctree::
     :maxdepth: 2
 
     installing
     configuration
-    your-first-set-of-documentation
+    what-is-a-docblock
+    generating-documentation