mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 09:57:41 +00:00
87 lines
3.5 KiB
Plaintext
87 lines
3.5 KiB
Plaintext
// 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 and multi-line string, 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 must
|
|
be removed and 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
|
|
|
|
*/
|