contrib/neo_doxygen/README.md

   1 # neo_doxygen
   2
   3 This project provides a tool to convert a Doxygen XML output into a model in
   4 Neo4j that is readable by the `nx` tool.
   5
   6
   7 ## Installation
   8
   9 Ensure that you have a working version of `nitc` in `../../bin` then run `make`
  10 in the present directory. The executable will be then generated at
  11 `bin/neo_doxygen`.
  12
  13
  14 ## Usage
  15
  16 Here is the procedure to generate an HTML documentation of a project using the
  17 formatting of Nitdoc:
  18
  19 1. First run Doxygen to generate an XML output of the documentation. In order to do
  20 this, you have to enable the `GENERATE_XML` option. Note that you can disable
  21 the `XML_PROGRAMLISTING` to speed up the process and save disk space.
  22
  23         <strong>Important</strong>
  24
  25         `neo_doxygen` do not read the `index.xml` file to know which file to load. As a
  26         result, it may read files let by previous runs of Doxygen. To avoid producing
  27         garbage, always clear the destination directory of the XML files before running
  28         Doxygen.
  29
  30         Example: `rm -rf doxygen/xml && doxygen Doxyfile`
  31
  32 2. Use `bin/neo_doxygen` to generate the Neo4j graph. For details, run
  33 `bin/neo_doxygen --help`.
  34
  35         <strong>Important</strong>
  36
  37         `neo_doxygen` do not remove what is already in the graph. So, you have to
  38         manualy clear the graph (or at least, the subgraph contaning all the nodes
  39         labelled with the specified project name) between each run.
  40
  41         For an example of how to delete an entire Neo4j database, see
  42         `make reset-neo`.
  43
  44         Example: `make reset-neo && neo_doxygen my_project doxygen/xml`
  45
  46 3. Use the `nx` tool to generate the HTML documentation from the previously
  47 generated graph.
  48
  49         Note: `nx` need to be configured before usage. For more details, refer to
  50         the documentation of `nx`.
  51
  52         Example: `nx neo doc my_project`
  53
  54
  55 ## Shell scripts
  56
  57 The two shell scripts (`gen-one.sh` and `gen-all.sh`) are provided to automate
  58 the execution of `neo_doxygen` and `nx` for some typical cases and to give a
  59 starting for the development of similar scripts. In order for them to work,
  60 each project on which they operate **must** contain the following files:
  61
  62  * The `.nx_config` configuration file for the `nx` tool, located at the root
  63         of the project.
  64
  65  * The XML documents generated by Doxygen, located in the `doxygen/xml`
  66         directory.
  67
  68 Also, they **must** be run with the current working directory set to the present
  69 directory. `gen-one.sh` handle only one project at a time while `gen-all.sh`
  70 works on a collection of projects grouped in a directory. For detail about how
  71 to invoke each script, see the comments in these scripts.
  72
  73
  74 ## Brief descriptions
  75
  76 To populate the first line of a description (used as brief description in
  77 Nitdoc), `neo_doxygen` uses the brief description provided by Doxygen. So, you
  78 may need to change settings like `JAVADOC_AUTOBRIEF`, `QT_AUTOBRIEF` and
  79 `MULTILINE_CPP_IS_BRIEF` in Doxygen to make `neo_doxygen` properly split the
  80 brief description from the detailed description. In absence of brief
  81 description, `neo_doxygen` will use the first block (usually, the first
  82 paragraph) of the detailed as brief description.
  83
  84
  85 ## Python
  86
  87 The built-in filter of Doxygen for Python is very basic. For example, it
  88 recognizes anything in the “docstrings” as verbatim detailed description. In
  89 order to enhance the processing of the Python scripts, the
  90 [doxypypy](https://github.com/Feneric/doxypypy) filter may be used.