# neo_doxygen

This project provides a tool to convert a Doxygen XML output into a model in
Neo4j that is readable by the `nx` tool.


## Installation

Ensure that you have a working version of `nitc` in `../../bin` then run `make`
in the present directory. The executable will be then generated at
`bin/neo_doxygen`.


## Usage

Here is the procedure to generate an HTML documentation of a project using the
formatting of Nitdoc:

1. First run Doxygen to generate an XML output of the documentation. In order to do
this, you have to enable the `GENERATE_XML` option. Note that you can disable
the `XML_PROGRAMLISTING` to speed up the process and save disk space.

	<strong>Important</strong>

	`neo_doxygen` do not read the `index.xml` file to know which file to load. As a
	result, it may read files let by previous runs of Doxygen. To avoid producing
	garbage, always clear the destination directory of the XML files before running
	Doxygen.

	Example: `rm -rf doxygen/xml && doxygen Doxyfile`

2. Use `bin/neo_doxygen` to generate the Neo4j graph. For details, run
`bin/neo_doxygen --help`.

	<strong>Important</strong>

	`neo_doxygen` do not remove what is already in the graph. So, you have to
	manualy clear the graph (or at least, the subgraph contaning all the nodes
	labelled with the specified project name) between each run.

	For an example of how to delete an entire Neo4j database, see
	`make reset-neo`.

	Example: `make reset-neo && neo_doxygen my_project doxygen/xml`

3. Use the `nx` tool to generate the HTML documentation from the previously
generated graph.

	Note: `nx` need to be configured before usage. For more details, refer to
	the documentation of `nx`.

	Example: `nx neo doc my_project`


## Shell scripts

The two shell scripts (`gen-one.sh` and `gen-all.sh`) are provided to automate
the execution of `neo_doxygen` and `nx` for some typical cases and to give a
starting for the development of similar scripts. In order for them to work,
each project on which they operate **must** contain the following files:

 * The `.nx_config` configuration file for the `nx` tool, located at the root
	of the project.

 * The XML documents generated by Doxygen, located in the `doxygen/xml`
	directory.

Also, they **must** be run with the current working directory set to the present
directory. `gen-one.sh` handle only one project at a time while `gen-all.sh`
works on a collection of projects grouped in a directory. For detail about how
to invoke each script, see the comments in these scripts.


## Brief descriptions

To populate the first line of a description (used as brief description in
Nitdoc), `neo_doxygen` uses the brief description provided by Doxygen. So, you
may need to change settings like `JAVADOC_AUTOBRIEF`, `QT_AUTOBRIEF` and
`MULTILINE_CPP_IS_BRIEF` in Doxygen to make `neo_doxygen` properly split the
brief description from the detailed description. In absence of brief
description, `neo_doxygen` will use the first block (usually, the first
paragraph) of the detailed as brief description.


## Python

The built-in filter of Doxygen for Python is very basic. For example, it
recognizes anything in the “docstrings” as verbatim detailed description. In
order to enhance the processing of the Python scripts, the
[doxypypy](https://github.com/Feneric/doxypypy) filter may be used.