mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-08-22 09:57:41 +00:00
78 lines
3.5 KiB
Plaintext
78 lines
3.5 KiB
Plaintext
// Copyright (C) 2018 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. Several tools have to
|
|
be present in the system: docbook environment, links and several others.
|
|
You can generate this by doing:
|
|
@code
|
|
$ ./configure --enable-generate-docs
|
|
$ cd doc/
|
|
$ make guide
|
|
@endcode
|
|
|
|
The output files will be generated in doc/guide/ directory.
|
|
|
|
Since Kea 1.5, this doc has appendix A that lists all Kea commands. That
|
|
appendix is generated using a small tool called docgen. The basic principle
|
|
is that for every command there is a JSON file that briefly describes the major
|
|
aspects of the new command, 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 docgen tool that will generate
|
|
api.xml that will be used by make guide. There is no need to generate this,
|
|
unless you alter description of existing commands or add a new one.
|
|
|
|
@section docsNewCommand Documenting new command
|
|
|
|
There are several steps needed to document a new API command:
|
|
|
|
1. edit docgen/cmds-list and add the new command
|
|
2. ./configure --enable-generate-docs
|
|
3. make - you need to build the sources first, am afraid. The reason why you
|
|
need to do this is that the tool kea-docgen depends on libkea-cc as it
|
|
loads JSON files. This means that the libs need to be built first.
|
|
4. (optional) run: make templates
|
|
This will go through the list of commands listed in cmds-list
|
|
and will check if there are corresponding JSON files in api/name.json
|
|
If the file is missing, a new JSON will be created using template.
|
|
If you dislike this generator, you can always use api/_template.json
|
|
and copy it over under the name of a new command.
|
|
5. Edit api/command-name.json. If the command is provided by the daemon
|
|
out of its own (and not via hook), simply delete the hook entry.
|
|
If you don't want to provide command syntax (cmd-syntax key),
|
|
any comments about the syntax (cmd-comment key) or response syntax
|
|
(resp-syntax) or any comment about response (resp-comment), simply
|
|
remove those unused keys. The generator will attempt to generate
|
|
boilerplates for it.
|
|
6. Generate api.xml: make api
|
|
7. Rebuild User's Guide as usual: make guide
|
|
|
|
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.
|
|
|
|
@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
|
|
$ make devel
|
|
@endcode
|
|
|
|
*/ |