From: Tomek Mrugalski Date: Fri, 5 Oct 2018 16:53:06 +0000 (+0200) Subject: [#10,!3] doc building process explained. X-Git-Tag: 176-update-to-sysrepo-0-7-6-release_base~78 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=ccfbaf501416b4febfe085629b69b082ea548a7e;p=thirdparty%2Fkea.git [#10,!3] doc building process explained. --- diff --git a/doc/Makefile.am b/doc/Makefile.am index a4634fa714..acd0a56ee7 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -63,6 +63,9 @@ nobase_dist_doc_DATA += examples/netconf/comments.json nobase_dist_doc_DATA += examples/netconf/simple.json nobase_dist_doc_DATA += examples/netconf/simple-dhcp4.json +# These are files that document our APIs. They're not really needed as the +# content is included in the api.xml, but may be useful for people who +# want to document the API. EXTRA_DIST += api/build-report.json EXTRA_DIST += api/cache-clear.json api/cache-get.json EXTRA_DIST += api/cache-insert.json api/cache-load.json @@ -109,6 +112,29 @@ guide: clean: rm -rf html +# There are several steps needed to document 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 gerate +# boilerplates for it. +# 6. Generate api.xml: make api +# 7. Rebuild User's Guide as usual: make guide + # This target will generate templates. There's no need to run it, unless # new commands have been added or there are existing commands that are # still not documented.