neo_doxygen - 

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.

    Important

    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.

    Important

    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 filter may be used.

Content