diff options
Diffstat (limited to 'doc/devel/doc.dox')
| -rw-r--r-- | doc/devel/doc.dox | 86 |
1 files changed, 86 insertions, 0 deletions
diff --git a/doc/devel/doc.dox b/doc/devel/doc.dox new file mode 100644 index 0000000..cde7f90 --- /dev/null +++ b/doc/devel/doc.dox @@ -0,0 +1,86 @@ +// 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 + +*/ |