From: Tomek Mrugalski Date: Tue, 29 Oct 2019 17:56:44 +0000 (+0100) Subject: [#10,!3] Section about generating documentation added. X-Git-Tag: 176-update-to-sysrepo-0-7-6-release_base~18 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=5d2e4d6fcc182a19eafa895abc35b1aee599fd23;p=thirdparty%2Fkea.git [#10,!3] Section about generating documentation added. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index 6f0c22a1e4..951c257a19 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -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 diff --git a/doc/devel/doc.dox b/doc/devel/doc.dox new file mode 100644 index 0000000000..5af28f24fe --- /dev/null +++ b/doc/devel/doc.dox @@ -0,0 +1,78 @@ +// 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 diff --git a/doc/devel/mainpage.dox b/doc/devel/mainpage.dox index 5bed68f9d9..92a316c2a1 100644 --- a/doc/devel/mainpage.dox +++ b/doc/devel/mainpage.dox @@ -141,6 +141,7 @@ * - @subpage logNotes * - @subpage LoggingApi * - @subpage SocketSessionUtility + * - @subpage docs * - Documentation warnings and errors * */