ntopng/doc/src

Documentation

Ntopng documentation uses read the docs and .rst file format.

Requirements

On ubuntu:

apt-get install doxygen
pip install breathe sphinx==1.7.9

Note: newer sphinx versions (e.g. 1.8.0) have a bug with search: https://github.com/sphinx-doc/sphinx/issues/5460

Generate

The ntopng documentation can be generated by executing make release.

It can be easily tested locally by running a python webserver:

  pushd _build/html; python3 -m http.server 8080; popd

Lua C API

The Lua C API documentation can be found inside the api/lua_c directory.

The functions documentation is written in .lua file (e.g. api/lua_c/ntop/ntop_users.lua). These are the files to modify to update the API documentation.

Functions are organized in a directory structure in the form api/lua_c/{object}/{api_group}.lua, where {object} is a C API reg (eg. interface) and {api_group} is a group of API functions relevant to the same topic (e.g. interface_hosts is for API functions that work with hosts).

Only a subset of the functions defined in src/LuaEngine.cpp are documented as API. They are marked with the // ***API*** comment. Whenever an API function is modified, the corresponding documentation file should be updated.

Here is how to perform some recurrent operations on the documentation:

• Add/modify a function documentation: e.g. to update the ntop.setCache documentation, the file api/lua_c/ntop/ntop_cache.lua should be modified.

• Add a new group of API functions for an existing C API reg: e.g. to group together all the host pools functions, the following modifications should be performed:

  • create api/lua_c/interface/interface_host_pools.lua.
  • create api/lua_c/interface/interface_host_pools.rst. Adapt this from an existing .rst.
  • edit api/lua_c/interface/index.rst and add interface_host_pools to the toctree section.

• Add a new C API reg: e.g. to add a new db reg so that we can call db.some_function functions, it's necessary to:

  • create api/lua_c/db/index.rst. Adapt this from an existing .rst.
  • edit api/lua_c/index.rst and add db/index to the toctree section.

Fixing API prefixes

Lua C API usually have a prefix which indicates the Lua table under which the API is present, e.g. ntop.isAdministrator has the ntop prefix, whereas interface.getid() has the interface interface prefix. In order to correctly show such prefix in the documentation its necessary to edit the _static/css/ntop.css file and add a CSS content definition.