README

DocGenerator
--------------

:Maintainers: Quentin Mathe <quentin.mathe@gmail.com>, Nicolas Roard
:Authors: Nicolas Roard, Quentin Mathe
:License: Modified BSD License
:Version: 0.1

etdocgen (Etoile Doc Generator) is a command-line tool that can generate HTML pages from various source documents and templates.

Its main use case is to generate the Etoile documentation; it reads gsdoc files (which are files containing an XML representation of a source code, generated by the ``autogsdoc`` tool from GNUstep), and splits or consolidates them into pages based on various rules. In the end, it generates a HTML representation of each page by combining different other files (as specified by the page template):

*  a HTML template (option ``-t``)
*  a menu file (option ``-m``)


Build and Install
-----------------

Read INSTALL document.


Mac OS X support
----------------

**Warning:** Xcode 4 is required to build the project.

DocGenerator is supported on Mac OS X and comes with a Xcode project.

The Xcode project requires:

* EtoileFoundation Xcode project (see Frameworks/EtoileFoundation)
* autogsdoc tool from GNUstep Base additions
* Graphviz library
* markdown tool (aka **Discount**)

For further details, see INSTALL.

To build DocGenerator on Mac OS X, select etdocgen in the target menu. You can then build and run this target, the tool will automatically generate test documentation from the TestFiles contents. The arguments and options passed to the tool for the generated test documenated are under the Run section of the DocGenerator scheme.

For generating the test documentation, the current directory must be set to the Documentation subdirectory of DocGenerator project directory. DocGenerator scheme sets this working directory by relying on $PROJECT_DIR (a built-in Xcode variable).


Usage
-----

You can use etdocgen tool directly, as ``etdocgen  --help`` explains it.

If the code to be documented belongs to Etoile, include documentation.make in your module GNUmakefile right after etoile.make. documentation.make is located at the root of the repository along etoile.make. Once documentation.make is included, you can generate the documentation as explained in the INSTALL file at the root of the repository.

As an example, here is DocGeneration GNUmakefile:

	include $(GNUSTEP_MAKEFILES)/common.make

	CC = clang

	TOOL_NAME = etdocgen

	$(TOOL_NAME)_TOOL_LIBS = -lEtoileFoundation -lgvc

	$(TOOL_NAME)_OBJC_FILES = $(wildcard *.m)

	include $(GNUSTEP_MAKEFILES)/tool.make
	-include ../../../etoile.make
	-include ../../../documentation.make

Just type ``make`` doc to generate the documatation in the current module directory, a new *Documentation* directory should appear. To eliminate the documentation and its intermediate files, type ``make clean-doc``.

You can control the documentation generation e.g. where are the source files located, which kind of files should be processed, provides a custom menu etc. by redefining the variables present in documentation.make. Read the code comments in documentation.make to see what is possible. documentation.make tries to handle various module organizations transparently, thereby including documentation.make should be enough usually.


Template tags
-------------

Here are some tags present in the templates (see the Templates directory).

* ``<!-- etoile-header -->`` will insert the generated header from gsdoc file(s)
* ``<!-- etoile-methods -->`` will insert the methods extracted from a gsdoc file(s)
* ``<!-- etoile-menu -->`` will insert the content of the menu file
* ``<!-- etoile-document -->`` will insert the content of the html document


Developer Notes
===============

For now, DocGenerator is limited to a tool. In a future version, it should be splitted into a framework and a tool.:w