Create Valadoc Developer Guide (#47)

* Add Valadoc Guide section under "Developer Guides"

* Started work on Valadoc Guidee quick start page

* Improve grammar in Valadoc quick start guide

* Add example and images of geneated documentation to quick start example

* Fix formatting issues in quick start guide

* Add command line tool instructions

* Add valadoc installation warning to command line tool instructions

* Started documenting formatting syntax

* Add text highlighting syntax example

* Add lists syntax example

* Add code block markup example

* Dedicated favicon file now being used

* Add Images and Links markup

* Fix grammar in formatting page

* Fix fomatting in formatting page

* Add table markup

* Add header markup

* Add infomation about valadoc taglets

* Add info about contributing to Valadoc

* Fix typo in formatting page

* Fix formatting in taglets page

* Fix links and grammar in contributing to valadoc page

source/conf.py

@@ -68,7 +68,7 @@
 html_css_files = ['gnome.css']
 
 html_logo = 'logo.png'
-html_favicon = 'logo.png'
+html_favicon = 'favicon.png'
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,

source/developer-guides/bindings/writing-a-vapi-manually.rst

@@ -1,14 +1,14 @@
 Writing a VAPI Manually
 =======================
 
-This document intends to be a tutorial and reference on how to write a Vala binding to an existing C library. If the library uses GLib, do not follow this document. Instead read :doc:`Generating a VAPI with GObject Introspection </developer-guides/bindings/generating-a-vapi-with-gobject-introspection>`. A library may not follow the GLib coding practices precisely, but it is better to fix the library to work with GObject Introspection than to write a manual binding. 
+This document intends to be a tutorial and reference on how to write a Vala binding to an existing C library. If the library uses GLib, do not follow this document. Instead read :doc:`Generating a VAPI with GObject Introspection </developer-guides/bindings/generating-a-vapi-with-gobject-introspection>`. A library may not follow the GLib coding practices precisely, but it is better to fix the library to work with GObject Introspection than to write a manual binding.
 
 C programmers are a rather liberal bunch; certain procedures are done in a multitude of ways depending on the mood of the programmer, whereas Vala is much more restricted. This guide cannot possibly cover all possible cases of different APIs written by C programmers. It is your job to understand the C API and present it with Vala-friendly semantics.
 
 There is a lot of material in this document and that can make it hard to take in at first. A practical approach to working through the tutorial would be to:
 
 1. | Bind an enum first because enums are easy to test.
- 
+
    | Once your test gives the expected result you know that the build process works. This means working through the "Getting Started" section and the "Enums and Flags" sub-section. Binding an enum also introduces the idea that there isn't a straight mapping from C to Vala
 
 2. | Bind the creation and destruction of a compact class next.
@@ -26,4 +26,4 @@ The above assumes that the library is written in an object oriented style of C.
    :maxdepth: 1
    :numbered:
 
-   */*
+   writing-a-vapi-manually/*

source/developer-guides/documentation.rst

@@ -0,0 +1,8 @@
+Documentation
+=============
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+
+   documentation/*

source/developer-guides/documentation/valadoc-guide.rst

@@ -0,0 +1,16 @@
+Valadoc Guide
+=============
+
+``valadoc`` is a command line tool that generates Vala programming documentation from a library's API (Application Programming Interface).
+
+The library's API can be :doc:`written manually </developer-guides/bindings/writing-a-vapi-manually>` in a VAPI file or :doc:`generated automatically </developer-guides/bindings/generating-a-vapi-with-gobject-introspection>` from source files and held in a GIR (GObject Introspection Repository) file. valadoc can generate documentation from both a VAPI file or a GIR file.
+
+If the library is written in Vala then valadoc can generate the documentation from the library's Vala source files.
+
+.. toctree::
+   :glob:
+   :maxdepth: 1
+   :numbered:
+
+   valadoc-guide/*
+

source/developer-guides/documentation/valadoc-guide/01-00-quick-start.rst

@@ -0,0 +1,75 @@
+Quick Start
+===========
+
+Basic Usage
+-----------
+
+.. warning::
+
+   The ``valadoc`` command line tool may not be bundled with your installation of the Vala. To follow this
+   example, install the ``valadoc`` tool in your operating system.
+
+First find an empty directory/create a new directory.
+
+Then, in that directory, create a file called ``lib.vala`` with the following contents:
+
+.. code-block:: vala
+
+   /**
+    * Make Simon say any phrase that you enter.
+    *
+    * Example:
+    * {{{
+    * public static void main (string[] args) {
+    *    print (simon_says ("Learn Valadoc!"));
+    * }
+    * }}}
+    *
+    * Will output:<<BR>>
+    * Simon says: "Learn Valadoc!"
+    *
+    * @since 1.0.0
+    */
+    public string simon_says (string phrase) {
+        return @"Simon says: \"$(phrase)\"";
+    }
+
+Generate the documentation for the by running the following command:
+
+.. code-block:: console
+
+   valadoc --package-name="simon-says" --package-version=1.0.0 -o docs lib.vala
+
+.. warning::
+
+   If you run this command more than once, you'll see the following error:
+
+   .. code-block:: output
+
+      error: File already exists
+
+   To avoid this issue, add the ``--force`` flag to the command
+
+   .. code-block:: console
+
+      valadoc --force --package-name="simon-says" --package-version=1.0.0 -o docs lib.vala
+
+   However, be aware that ``--force`` does not remove any documentation. It only adds and overwrites documentation.
+
+This will generate a the documentation of the code in the ``docs`` directory.
+
+Open ``docs/index.html`` in a web browser to view the generated documentation:
+
+.. image:: assets/simon-says-home.png
+   :alt: Simon Says Documentation Home
+
+Select the "simon-says" package to view its contents:
+
+.. image:: assets/simon-says-package.png
+   :alt: Simon Says Package Documentation
+
+Now, you can see the ``simon_says`` function that you wrote in ``lib.vala``. Select it to view the full documentation of the function:
+
+.. image:: assets/simon-says-function.png
+   :alt: Simon Says Function Documentation
+

source/developer-guides/documentation/valadoc-guide/02-00-command-line-tool.rst

@@ -0,0 +1,46 @@
+Command Line Tool
+=================
+
+.. warning::
+
+   The ``valadoc`` command line tool may not be bundled with your installation of the Vala.
+   You will need to find a way to install it on your operating system.
+
+Usage:
+
+.. code-block:: console
+
+   valadoc [OPTION...] FILE...
+
+Essential Options
+-----------------
+
+**-o,--directory=DIRECTORY**
+   Output directory of the generated documentation.
+
+   The name ofthe directory will also be used as the package name if a package name has not been explicitly
+   set and cannot be derived from any other sources
+
+**--package-name=NAME**
+   Sets the name of the package of the generated documentation.
+
+**--package-version=VERSION**
+   Sets the package version of the generated documentation.
+
+**--force**
+   Force the doumentation to be generated, even if the output directory already exists.
+
+   As stated in the :doc:`quick start guide </developer-guides/documentation/valadoc-guide/01-00-quick-start>`,
+   with this option set, generated documentation is only addd or overwritten.
+
+**--pkg=PAKAGE...**
+   Speify bindings to inlude in th documentation via their package names.
+
+**--version**
+   Display the vesrion number of the valadoc tool.
+
+**-h, --help**
+   View the list of all of the commands and options that ``valadoc`` supports.
+
+   You'll see additional options that aren't listed on this page when you use this option.
+

source/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup.rst

@@ -0,0 +1,27 @@
+Documentation Comment Markup
+============================
+
+Documentation Comment Structure
+-------------------------------
+
+.. code-block:: vala
+
+   /**
+    * [brief description]
+    *
+    * [long description]
+    *
+    * [taglets]
+    */
+
+.. note::
+
+   When no comments are present, Valadoc will only extact symbols to use in the documentation.
+
+In this chapter, we'll explain how to fill each section of a documentation comment.
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   03-00-documentation-comment-markup/*

source/developer-guides/documentation/valadoc-guide/03-00-documentation-comment-markup/03-01-brief-description.rst

@@ -0,0 +1,19 @@
+Brief Description
+=================
+
+The brief description is used thoughout the entire documentation as a short summary for the symbol you're documenting.
+
+Example
+-------
+
+.. code-block:: vala
+
+   /**
+    * This function returns true
+    *
+    */
+   public bool always_true () {
+       return true;
+   }
+
+