--- /dev/null
+// 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
projects / thirdparty / kea.git / commitdiff
