Adding upstream version 2.5.7.upstream/2.5.7upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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
+
+*/