neo_doxygen: Add a “README”.

Signed-off-by: Jean-Christophe Beaupré <jcbrinfo@users.noreply.github.com>

diff --git a/contrib/neo_doxygen/README.md b/contrib/neo_doxygen/README.md
new file mode 100644 (file)
index 0000000..67b0e52
--- /dev/null
+++ b/contrib/neo_doxygen/README.md
@@ -0,0 +1,71 @@
+# 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 `nitg` 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.