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:
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 theXML_PROGRAMLISTING
to speed up the process and save disk space.Important
neo_doxygen
do not read theindex.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
Use
bin/neo_doxygen
to generate the Neo4j graph. For details, runbin/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
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 ofnx
.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 thenx
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
- neo_doxygen: neo_doxygen (contrib/neo_doxygen)
- sh-lib: Libraries used by shell scripts. (contrib/neo_doxygen/sh-lib)
- src (contrib/neo_doxygen/src)
- doxml (contrib/neo_doxygen/src/doxml)
- compounddef:
compounddef
element reading. (contrib/neo_doxygen/src/doxml/compounddef.nit) - doc_listener: Documentation reading. (contrib/neo_doxygen/src/doxml/doc_listener.nit)
- doxml: Doxygen’s XML documents reading. (contrib/neo_doxygen/src/doxml/doxml.nit)
- doxyname: Adds a methods to convert Doxygen’s names into short names. (contrib/neo_doxygen/src/doxml/doxyname.nit)
- entitydef: Common SAX listeners for entity definitions. (contrib/neo_doxygen/src/doxml/entitydef.nit)
- language_specific: Handle language-specific parts of the importation. (contrib/neo_doxygen/src/doxml/language_specific.nit)
- listener: Basic SAX listeners. (contrib/neo_doxygen/src/doxml/listener.nit)
- memberdef:
memberdef
element reading. (contrib/neo_doxygen/src/doxml/memberdef.nit)
- compounddef:
- graph_store: A storage medium for a graph. (contrib/neo_doxygen/src/graph_store.nit)
- model (contrib/neo_doxygen/src/model)
- class_compound: Nodes for classes. (contrib/neo_doxygen/src/model/class_compound.nit)
- descriptions: Documentation associated to an entity. (contrib/neo_doxygen/src/model/descriptions.nit)
- graph: Graphs and basic entities. (contrib/neo_doxygen/src/model/graph.nit)
- inner_class: Adds the possibility to define inner classses. (contrib/neo_doxygen/src/model/inner_class.nit)
- linked_text: A text with links. (contrib/neo_doxygen/src/model/linked_text.nit)
- location: This module is used to model locations in source files. (contrib/neo_doxygen/src/model/location.nit)
- member: Members. (contrib/neo_doxygen/src/model/member.nit)
- model: The model used to populate the Neo4j graph. (contrib/neo_doxygen/src/model/model.nit)
- module_compound: Nodes for modules and files. (contrib/neo_doxygen/src/model/module_compound.nit)
- namespace_members: Add support for namespace’s members. (contrib/neo_doxygen/src/model/namespace_members.nit)
- type_entity: Typing and parameters. (contrib/neo_doxygen/src/model/type_entity.nit)
- neo_doxygen: Doxygen XML to Neo4j. (contrib/neo_doxygen/src/neo_doxygen.nit)
- tests: Test scripts for
neo_doxygen
. (contrib/neo_doxygen/src/tests)- neo_doxygen_doc_module_class (contrib/neo_doxygen/src/tests/neo_doxygen_doc_module_class.nit)
- neo_doxygen_dump: A variant of the
neo_doxygen
program that produces a debugging output of the graph instead of saving it. (contrib/neo_doxygen/src/tests/neo_doxygen_dump.nit) - neo_doxygen_file_compound (contrib/neo_doxygen/src/tests/neo_doxygen_file_compound.nit)
- neo_doxygen_graph_empty_project (contrib/neo_doxygen/src/tests/neo_doxygen_graph_empty_project.nit)
- neo_doxygen_namespace_members (contrib/neo_doxygen/src/tests/neo_doxygen_namespace_members.nit)
- tests: Base module for tests related to
neo_doxygen
. (contrib/neo_doxygen/src/tests/tests.nit)
- doxml (contrib/neo_doxygen/src/doxml)
- tests: Data files for tests. (contrib/neo_doxygen/tests)
- empty-project: This directory contains an empty project for testing purposes. (contrib/neo_doxygen/tests/empty-project)
- src (contrib/neo_doxygen/tests/empty-project/src)
- org (contrib/neo_doxygen/tests/empty-project/src/org)
- example (contrib/neo_doxygen/tests/empty-project/src/org/example)
- org (contrib/neo_doxygen/tests/empty-project/src/org)
- src (contrib/neo_doxygen/tests/empty-project/src)
- inner-class: This directory contains a dummy Java project for testing purposes. (contrib/neo_doxygen/tests/inner-class)
- java-project: This directory contains a dummy Java project for testing purposes. (contrib/neo_doxygen/tests/java-project)
- src (contrib/neo_doxygen/tests/java-project/src)
- org (contrib/neo_doxygen/tests/java-project/src/org)
- example (contrib/neo_doxygen/tests/java-project/src/org/example)
- org (contrib/neo_doxygen/tests/java-project/src/org)
- src (contrib/neo_doxygen/tests/java-project/src)
- python-def: This directory contains a dummy Python project for testing purposes. (contrib/neo_doxygen/tests/python-def)
- root-namespace: This directory contains a dummy Java project for testing purposes. (contrib/neo_doxygen/tests/root-namespace)
- empty-project: This directory contains an empty project for testing purposes. (contrib/neo_doxygen/tests/empty-project)