zephyr

History

Rodrigo Caballero fb74cd4a79 Add In-Code Documentation Guidelines The in-code Documentation Guidelines contains the best practices for documenting code using Doxygen. The guidelines offer options for both novice and expert developers to document their code in a compatible and correct manner. Fully marked and simplified templates are provided to ease the documentation effort. Examples taken directly from Tiny Mountain's code show the difference clearly. The .c files contained here are used for the examples only and do not have any function within Tiny Mountain. Finally, the doxygen.rst file was updated to include the new content. Change-Id: I6a39a54feed5fa95f2f21545c3967ff0755d85ae Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>		2016-02-05 20:14:12 -05:00
..
collaboration	ADD Collaboration Guideline ReST content files.	2016-02-05 20:14:01 -05:00
doxygen	Add In-Code Documentation Guidelines	2016-02-05 20:14:12 -05:00
installation	doc: indent code blocks	2016-02-05 20:14:11 -05:00
object	Add Object Documentation	2016-02-05 20:14:11 -05:00
Makefile	Add tools and Makefiles for Documentation	2016-02-05 20:13:58 -05:00
README.rst	doc: Fixed instructions for building documentation	2016-02-05 20:14:11 -05:00
conf.py	doc: put a 'Last update on: timestamp' in footer	2016-02-05 20:14:11 -05:00
disclaimers.rst	Add Disclaimer explaining that the documentation is a work in progress.	2016-02-05 20:14:11 -05:00
documentation_license.rst	ADD framework files for ReST content.	2016-02-05 20:14:00 -05:00
doxygen.config	doc: add nano kernel files and *.s pattern	2016-02-05 20:14:11 -05:00
index.rst	Add Disclaimer explaining that the documentation is a work in progress.	2016-02-05 20:14:11 -05:00
substitutions.rst	ADD framework files for ReST content.	2016-02-05 20:14:00 -05:00

README.rst

.. include:: substitutions.rst

Welcome to |codename|
#####################

.. This document is in Restructured Text Format.

   More information at `<http://sphinx-doc.org/rest.html>`_.
   This is a comment that won't show up in formatted output

Welcome to |project|.

Thank you for your interest in |project|. Read the instructions
carefully to generate the |project|'s documentation.


Documentation Notes
*******************

The documentation of |project| currently comprises the following items:

* An Installation Guide for Linux host systems

* A set of Collaboration Guidelines for the |project| project.

* Raw Doxygen output from the code base.

Installing the documentation processors
***************************************

Install the current version of :program:`Sphinx`, type:

.. code-block:: bash

   $ git clone https://github.com/sphinx-doc/sphinx.git sphinx

   $ cd sphinx

   $ sudo -E python setup.py install

   $ cd ..

   $ git clone https://github.com/michaeljones/breathe.git breathe

   $ cd breathe

   $ sudo -E python setup.py install

.. note::

   Make sure that :program:`Doxygen` is installed in your system.
   The installation of Doxygen is beyond the scope of this document.

Running the documentation generators
************************************

Assuming that the |project| tree with the doc patches is in
:file:`DIRECTORY`, type:

.. code-block:: bash

   $ cd DIRECTORY/doc

   $ make doxy html

Find the output in :file:`DIRECTORY/doc/_build/html/index.html`

Review the available formats with:

.. code-block:: bash

   $ make -C DIRECTORY/doc doxy html

If you want the LaTeX PDF output, you need to install all the Latex
packages first. That installation is beyond the scope of this document.