*************
Configuration
*************

GNATdoc can be configured via some attributes in the *Documentation* package of the root project file.

Documentation pattern
---------------------

The regular expression for recognizing doc comments can be specified via the
string attribute *Documentation_Pattern* of the *Documentation* package::

   package Documentation is
      for Documentation_Pattern use "^<";
      --  This considers comments beginning with "--<" to be documentation
   end Documentation;

If this attribute is not specified, all comments are considered to be
documentation.


Excluded project files
----------------------

By default GNATdoc recursively processes all the projects on which your root
project depends, except externally built projects.
This behavior can be modified by specifying the *Excluded_Project_Files*
attribute in the *Documentation* package of the root project::

   package Documentation is
      for Excluded_Project_Files use
        ("vss_config.gpr",
         "vss_gnat.gpr");
   end Documentation;

This list may include any project files directly or indirectly used by
the root project.


Output directory
----------------

The documentation is generated by default into a directory called
:file:`gnatdoc`, created under the object directory of the root project. This
behavior can be modified by specifying the attribute *Output_Dir* in the
*Documentation* package::

  package Documentation is
     for Output_Dir ("html") use "html";
  end Documentation;


Output customization
--------------------

The GNATdoc backends can use a set of static resources and templates files to control the final
rendering. By modifying these static resources and templates, you can control the
rendering of the generated documentation. The files used for generating the
documentation can be found under
:file:`<install_dir>/share/gnatdoc/<backend>`.
If you need a different layout from the proposed one, you can override those
files and provides your own set of files. The directory for user defined static resources
and templates can be specified via the string attribute *Resources_Dir* of the
*Documentation* package in the project file::

   package Documentation is
      for Resources_Dir ("html") use "docs/gnatdoc_html";
   end Documentation;

Each backend has own conventions on the layout of the resources directory: see
the documentation of the particular backend.


Images directories
------------------


List of directories to lookup for image files referenced in the documentation
can be defined with *Image_Dirs* attribute of the root project file::

   package Documentation is
      for Image_Dirs ("odf") use ("images");
   end Documentation;

By default paths are resolved relatively to the project file's root directory.