Commit 5d2e4d6f authored by Tomek Mrugalski's avatar Tomek Mrugalski

[#10,!3] Section about generating documentation added.

parent 0e8c2967
......@@ -7,6 +7,7 @@ EXTRA_DIST += devel/contribute.dox
EXTRA_DIST += devel/mainpage.dox
EXTRA_DIST += devel/terminology.dox
EXTRA_DIST += devel/unit-tests.dox
EXTRA_DIST += devel/doc.dox
nobase_dist_doc_DATA = examples/agent/comments.json
nobase_dist_doc_DATA += examples/agent/simple.json
......
// 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
*/
\ No newline at end of file
......@@ -141,6 +141,7 @@
* - @subpage logNotes
* - @subpage LoggingApi
* - @subpage SocketSessionUtility
* - @subpage docs
* - <a href="./doxygen-error.log">Documentation warnings and errors</a>
*
*/
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment