kea/doc/devel/doc.dox

// Copyright (C) 2018-2021 Internet Systems Consortium, Inc. ("ISC")
//
// This Source Code Form is subject to the terms of the Mozilla Public
// License, v. 2.0. If a copy of the MPL was not distributed with this
// file, You can obtain one at http://mozilla.org/MPL/2.0/.

/**

 @page docs Building Kea Documentation

 There are several types of documentation for Kea. The primary one, intended to
 be read by users, is User's Guide. It comes in HTML, PDF and txt format. All
 of them generated from the same sources. To generate this doc, you need to
 run configure script with --enable-generate-docs option. sphinx has to be
 enabled in the system.
 You can generate this by doing:
@code
$ ./configure --enable-generate-docs
$ make -C ./doc
@endcode

The output files will be generated in the ./doc/sphinx/_build directory.

The ARM has an appendix that lists all Kea commands. The commands are integrated
into RST using the tool located at doc/sphinx/api2doc.py. The basic principle
is that for every command there is a JSON file that briefly describes the major
aspects such as name, short description, expected syntax, expected response,
a hook that needs to be loaded, first Kea version where it appeared, etc.
Those JSON files are loaded by the api2doc.py tool that will generate api.txt
that will be used by sphinx. There is no need to call this tool explicitly.
It is called automatically when building the ARM.

Since Kea 1.9.9, the ARM has an appendix with the grammar. If there were new
parameters added, you can regenerate the grammars and the appendix with the
following procedure:

@code
$ autoreconf -i
$ ./configure --enable-generate-docs --enable-generate-parser
$ cd doc
$ make grammar
$ make -C sphinx html
@endcode

After that, inspect the html output and make sure it's ok, review changes in
\c doc/sphinx/grammar/ and then check in those that are something more than a date
update. The date is there, so we (and users) can determine if the grammar
is or isn't out of date.

@section docsNewCommand Documenting new command

There are several steps needed to document a new API command:

 1. Configure sources with ./configure --enable-generate-docs
 1. Copy src/share/api/_template.json to appropriate name.
 2. Remove comments from it and fill in the actual content.
 3. Update api_files.mk file in src/share/api/Makefile.am
 4. make html will generate multi-page html.
 5. make singlehtml will generate a single page html.

A word of caution regaring editing JSON files. The files themselves need to be
valid JSON files. They also often contain fields, such as command syntax or
command response, there are themselves a JSON or JSON like structures. That
means that some trickery with escaping double quotes will be involved. Note
there is no need to escape any other character, unless you want to specify
non-printable characters.

Also, while Kea's JSON parser supports comments, multi-line strings and extra
commas, they are not part of JSON standard. That means that external tools, such
as python or Sphinx parsers are not able to deal with them. Therefore comments
and extra commas must be removed. Long strings (such as command descriptions or
example invocations) are to be presented as a list of strings
e.g. [ "line1", "line2, "line3" ].

@section docsDevelGuide Generating Developer's Guide

Generating Developer's Guide is very simple, although you need to have
doxygen installed in your system. If you also have graphviz installed, it will
generate nice diagrams. To generate developer's guide, do the following commands:

@code
$ ./configure
$ cd doc/devel
$ make devel
@endcode

*/