mirror of
https://gitlab.isc.org/isc-projects/kea
synced 2025-09-02 15:05:16 +00:00
cleaned up api docgen, fixed duplicate labels in manuals
This commit is contained in:
Michal Nowikowski
2
doc/.gitignore
vendored
2
doc/.gitignore
vendored
@@ -1,2 +0,0 @@
|
||||
/version.ent
|
||||
html
|
||||
2
doc/docgen/.gitignore
vendored
2
doc/docgen/.gitignore
vendored
@@ -1,2 +0,0 @@
|
||||
kea-docgen
|
||||
*.json
|
||||
@@ -1,22 +0,0 @@
|
||||
SUBDIRS = .
|
||||
|
||||
AM_CPPFLAGS = -I$(top_srcdir)/src/lib -I$(top_builddir)/src/lib
|
||||
AM_CPPFLAGS += $(BOOST_INCLUDES)
|
||||
|
||||
AM_CXXFLAGS = $(KEA_CXXFLAGS)
|
||||
|
||||
if USE_STATIC_LINK
|
||||
AM_LDFLAGS = -static
|
||||
endif
|
||||
|
||||
if GENERATE_DOCS
|
||||
noinst_PROGRAMS = kea-docgen
|
||||
kea_docgen_SOURCES = kea_docgen.cc
|
||||
|
||||
EXTRA_DIST = generate-templates
|
||||
EXTRA_DIST += cmds-list
|
||||
|
||||
kea_docgen_LDADD = $(top_builddir)/src/lib/cc/libkea-cc.la
|
||||
kea_docgen_LDADD += $(top_builddir)/src/lib/exceptions/libkea-exceptions.la
|
||||
|
||||
endif
|
||||
@@ -1,488 +0,0 @@
|
||||
// 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/.
|
||||
|
||||
#include <iostream>
|
||||
#include <fstream>
|
||||
#include <sstream>
|
||||
#include <vector>
|
||||
#include <map>
|
||||
#include <set>
|
||||
#include <ctime>
|
||||
|
||||
#include <exceptions/exceptions.h>
|
||||
#include <cc/data.h>
|
||||
|
||||
using namespace std;
|
||||
using namespace isc;
|
||||
using namespace isc::data;
|
||||
|
||||
|
||||
/// @brief API documentation generator
|
||||
class DocGen {
|
||||
public:
|
||||
|
||||
/// Output location of a file.
|
||||
const string OUTPUT = "guide/api.xml";
|
||||
|
||||
/// Controls whether to print out extra information.
|
||||
bool verbose = false;
|
||||
|
||||
/// @brief Load JSON files that each contain description of an API command
|
||||
///
|
||||
/// @param files a vector with names of files.
|
||||
void loadFiles(const vector<string>& files) {
|
||||
|
||||
map <string, ElementPtr> commands;
|
||||
|
||||
int cnt = 0;
|
||||
|
||||
int errors = 0; // number of errors encountered
|
||||
|
||||
try {
|
||||
for (auto f : files) {
|
||||
string cmd = f;
|
||||
size_t pos = f.find_last_of('/');
|
||||
if (pos != string::npos) {
|
||||
cmd = f.substr(pos + 1, -1);
|
||||
}
|
||||
cmd = cmd.substr(0, cmd.find("."));
|
||||
|
||||
if (cmd == "_template") {
|
||||
cout << "Skipping template file (_template.json)" << endl;
|
||||
continue;
|
||||
}
|
||||
|
||||
try {
|
||||
cout << "Loading description of command " << cmd << "... ";
|
||||
ElementPtr x = Element::fromJSONFile(f, false);
|
||||
cout << "loaded, sanity check...";
|
||||
|
||||
sanityCheck(f, x);
|
||||
|
||||
cmds_.insert(make_pair(cmd, x));
|
||||
cout << " looks ok." << endl;
|
||||
|
||||
} catch (const exception& e) {
|
||||
cout << "ERROR: " << e.what() << endl;
|
||||
errors++;
|
||||
}
|
||||
|
||||
if (errors) {
|
||||
continue;
|
||||
}
|
||||
|
||||
cnt++;
|
||||
}
|
||||
} catch (const Unexpected& e) {
|
||||
isc_throw(Unexpected, e.what() << " while processing "
|
||||
<< cnt + 1 << " file out of " << files.size());
|
||||
}
|
||||
|
||||
cout << "Loaded " << cmds_.size() << " commands out of " << files.size()
|
||||
<< " file(s), " << errors << " error(s) detected." << endl;
|
||||
if (errors) {
|
||||
isc_throw(Unexpected, errors << " error(s) detected while loading JSON files");
|
||||
}
|
||||
}
|
||||
|
||||
/// @brief checks if mandatory string parameter is specified
|
||||
///
|
||||
/// @param x a map that is being checked
|
||||
/// @param name name of the string element expected to be there
|
||||
/// @param fname name of the file (used in error reporting)
|
||||
/// @throw Unexpected if missing, different type or empty
|
||||
void requireString(const ElementPtr& x, const string& name, const string& fname) {
|
||||
if (!x->contains(name)) {
|
||||
isc_throw(Unexpected, "Mandatory '" + name + " field missing while "
|
||||
"processing file " + fname);
|
||||
}
|
||||
if (x->get(name)->getType() != Element::string) {
|
||||
isc_throw(Unexpected, "'" + name + " field is present, but is not a string"
|
||||
" in file " + fname);
|
||||
}
|
||||
if (x->get(name)->stringValue().empty()) {
|
||||
isc_throw(Unexpected, "'" + name + " field is present, is a string, but is "
|
||||
"empty in file " + fname);
|
||||
}
|
||||
}
|
||||
|
||||
/// @brief checks if mandatory list parameter is specified
|
||||
///
|
||||
/// @param x a map that is being checked
|
||||
/// @param name name of the list element expected to be there
|
||||
/// @param fname name of the file (used in error reporting)
|
||||
/// @throw Unexpected if missing, different type or empty
|
||||
void requireList(const ElementPtr& x, const string& name, const string& fname) {
|
||||
if (!x->contains(name)) {
|
||||
isc_throw(Unexpected, "Mandatory '" + name + " field missing while "
|
||||
"processing file " + fname);
|
||||
}
|
||||
if (x->get(name)->getType() != Element::list) {
|
||||
isc_throw(Unexpected, "'" + name + " field is present, but is not a list "
|
||||
"in file " + fname);
|
||||
}
|
||||
|
||||
ConstElementPtr l = x->get(name);
|
||||
|
||||
if (l->size() == 0) {
|
||||
isc_throw(Unexpected, "'" + name + " field is a list, but is empty in file "
|
||||
+ fname);
|
||||
}
|
||||
|
||||
// todo: check that every element is a string
|
||||
}
|
||||
|
||||
/// @brief Checks that the essential parameters for each command are defined
|
||||
///
|
||||
/// @param fname name of the file the data was read from (printed if error is detected)
|
||||
/// @param x a JSON map that contains content of the file
|
||||
void sanityCheck(const string& fname, const ElementPtr& x) {
|
||||
requireString(x, "name", fname);
|
||||
requireString(x, "brief", fname);
|
||||
requireList (x, "support", fname);
|
||||
requireString(x, "avail", fname);
|
||||
requireString(x, "brief", fname);
|
||||
|
||||
// They're optional.
|
||||
//requireString(x, "cmd-syntax", fname);
|
||||
//requireString(x, "cmd-comment", fname);
|
||||
//requireString(x, "resp-syntax", fname);
|
||||
//requireString(x, "resp-comment", fname);
|
||||
}
|
||||
|
||||
/// @brief Writes ISC copyright note to the stream
|
||||
///
|
||||
/// @param f stream to write copyrights to
|
||||
void generateCopyright(stringstream& f) {
|
||||
f << "<!--" << endl;
|
||||
|
||||
std::time_t t = time(0);
|
||||
std::tm* now = std::localtime(&t);
|
||||
|
||||
if (now->tm_year + 1900 == 2018) {
|
||||
f << " - Copyright (C) 2018 Internet Systems Consortium, Inc. (\"ISC\")" << endl;
|
||||
} else {
|
||||
// Whoaa! the future is now!
|
||||
f << " - Copyright (C) 2018-" << (now->tm_year + 1900) << " Internet Systems Consortium, Inc. (\"ISC\")" << endl;
|
||||
}
|
||||
f << " -" << endl;
|
||||
f << " - This Source Code Form is subject to the terms of the Mozilla Public" << endl;
|
||||
f << " - License, v. 2.0. If a copy of the MPL was not distributed with this" << endl;
|
||||
f << " - file, You can obtain one at http://mozilla.org/MPL/2.0/." << endl;
|
||||
f << " -->" << endl;
|
||||
f << endl;
|
||||
f << "<!-- autogenerated using cmd_docgen. Do not edit by hand! -->" << endl;
|
||||
}
|
||||
|
||||
/// @brief generates a link to command
|
||||
///
|
||||
/// @param f stream to write the generated link to
|
||||
/// @param cmd name of the command
|
||||
void generateCmdLink(stringstream& f, const string& cmd) {
|
||||
f << "<command><link linkend=\"ref-" << cmd << "\">" << cmd
|
||||
<< "</link></command>" << endl;
|
||||
}
|
||||
|
||||
/// @brief generates lists of all commands.
|
||||
///
|
||||
/// Currently there are several lists (or rather lists of lists). They all enumerate
|
||||
/// commands, but each list serving a different purpose:
|
||||
/// - list of commands supported by a daemon
|
||||
/// - list of commands provided by a hook
|
||||
///
|
||||
/// @param f stream to write the generated lists to
|
||||
void generateLists(stringstream& f) {
|
||||
// Generate a list of all commands
|
||||
f << " <para>Kea currently supports " << cmds_.size() << " commands:" << endl;
|
||||
|
||||
bool first = true;
|
||||
for (auto cmd : cmds_) {
|
||||
if (!first) {
|
||||
f << ", ";
|
||||
}
|
||||
generateCmdLink(f, cmd.first);
|
||||
|
||||
first = false;
|
||||
}
|
||||
|
||||
f << ".</para>" << endl;
|
||||
|
||||
// Generate a list of components:
|
||||
set<string> all_daemons;
|
||||
set<string> all_hooks;
|
||||
for (auto cmd : cmds_) {
|
||||
auto daemons = cmd.second->get("support");
|
||||
auto hook = cmd.second->get("hook");
|
||||
for (int i = 0; i < daemons->size(); i++) {
|
||||
string daemon = daemons->get(i)->stringValue();
|
||||
if (all_daemons.find(daemon) == all_daemons.end()) {
|
||||
all_daemons.insert(daemon);
|
||||
}
|
||||
}
|
||||
if (hook) {
|
||||
string hook_txt = hook->stringValue();
|
||||
if (all_hooks.find(hook_txt) == all_hooks.end()) {
|
||||
all_hooks.insert(hook_txt);
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cout << all_daemons.size() << " daemon(s) detected." << endl;
|
||||
cout << all_hooks.size() << " hook lib(s) detected." << endl;
|
||||
|
||||
for (auto daemon : all_daemons) {
|
||||
f << "<para xml:id=\"commands-" << daemon << "\">"
|
||||
<< "Commands supported by " << daemon << " daemon: ";
|
||||
|
||||
bool first = true;
|
||||
for (auto cmd : cmds_) {
|
||||
|
||||
auto daemons = cmd.second->get("support");
|
||||
for (auto d : daemons->listValue()) {
|
||||
if (d->stringValue() == daemon) {
|
||||
if (!first) {
|
||||
f << ", ";
|
||||
}
|
||||
generateCmdLink(f, cmd.first);
|
||||
first = false;
|
||||
break; // get to next command
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
f << ".</para>" << endl;
|
||||
}
|
||||
|
||||
|
||||
for (auto hook : all_hooks) {
|
||||
f << "<para xml:id=\"commands-" << hook << "-lib\">"
|
||||
<< "Commands supported by " << hook << " hook library: ";
|
||||
|
||||
bool first = true;
|
||||
for (auto cmd : cmds_) {
|
||||
|
||||
auto daemon_hook = cmd.second->get("hook");
|
||||
if (!daemon_hook || daemon_hook->stringValue() != hook) {
|
||||
continue;
|
||||
}
|
||||
if (!first) {
|
||||
f << ", ";
|
||||
}
|
||||
generateCmdLink(f, cmd.first);
|
||||
first = false;
|
||||
}
|
||||
|
||||
f << ".</para>" << endl;
|
||||
}
|
||||
|
||||
}
|
||||
|
||||
/// @brief generates the whole API documentation
|
||||
void generateOutput() {
|
||||
|
||||
stringstream f;
|
||||
|
||||
generateCopyright(f);
|
||||
|
||||
f << "<appendix xmlns=\"http://docbook.org/ns/docbook\" version=\"5.0\" xml:id=\"api\">"
|
||||
<< endl;
|
||||
f << " <title>API Reference</title>" << endl;
|
||||
|
||||
|
||||
generateLists(f);
|
||||
|
||||
// Generate actual commands references.
|
||||
generateCommands(f);
|
||||
|
||||
f << "</appendix>" << endl;
|
||||
|
||||
ofstream file(OUTPUT.c_str(), ofstream::trunc);
|
||||
file << f.str();
|
||||
if (verbose) {
|
||||
cout << "----------------" << endl;
|
||||
cout << f.str();
|
||||
cout << "----------------" << endl;
|
||||
}
|
||||
file.close();
|
||||
|
||||
cout << "Output written to " << OUTPUT << endl;
|
||||
}
|
||||
|
||||
/// @brief generate sections for all commands
|
||||
///
|
||||
/// @param f stream to write the commands to
|
||||
void generateCommands(stringstream& f){
|
||||
|
||||
for (auto cmd : cmds_) {
|
||||
f << "<!-- start of " << cmd.first << " -->" << endl;
|
||||
f << "<section xml:id=\"reference-" << cmd.first << "\">" << endl;
|
||||
f << "<title>" << cmd.first << " reference</title>" << endl;
|
||||
generateCommand(f, cmd.second);
|
||||
f << "</section>" << endl;
|
||||
f << "<!-- end of " << cmd.first << " -->" << endl;
|
||||
f << endl;
|
||||
}
|
||||
}
|
||||
|
||||
/// @brief replace all strings
|
||||
///
|
||||
/// @param str [in,out] this string will have some replacements
|
||||
/// @param from what to replace
|
||||
/// @param to what to replace with
|
||||
void replaceAll(std::string& str, const std::string& from, const std::string& to) {
|
||||
if(from.empty())
|
||||
return;
|
||||
size_t start_pos = 0;
|
||||
while((start_pos = str.find(from, start_pos)) != std::string::npos) {
|
||||
str.replace(start_pos, from.length(), to);
|
||||
start_pos += to.length();
|
||||
}
|
||||
}
|
||||
|
||||
/// @brief escapes string to be safe for XML (docbook)
|
||||
///
|
||||
/// @param txt string to be escaped
|
||||
/// @return escaped string
|
||||
string escapeString(string txt) {
|
||||
|
||||
replaceAll(txt, "<", "<");
|
||||
replaceAll(txt, ">", ">");
|
||||
return (txt);
|
||||
}
|
||||
|
||||
/// @brief generates standard description of command's response
|
||||
///
|
||||
/// If a command doesn't have response syntax specified, we will
|
||||
/// assume it follows the usual syntax and provide the default description.
|
||||
string standardResponseSyntax() {
|
||||
stringstream t;
|
||||
|
||||
t << "{" << endl
|
||||
<< " \"result\": <integer>," << endl
|
||||
<< " \"text\": <string>" << endl
|
||||
<< "}" << endl;
|
||||
return (t.str());
|
||||
}
|
||||
|
||||
/// @brief generates standard description of command's comment
|
||||
///
|
||||
/// If a command doesn't have response syntax comment specified, we will
|
||||
/// assume it follows the usual syntax and provide the default description.
|
||||
string standardResponseComment() {
|
||||
stringstream t;
|
||||
|
||||
t << "Result is an integer representation of the status. Currently supported"
|
||||
<< " statuses are:" << endl
|
||||
<< "<itemizedlist>" << endl
|
||||
<< " <listitem><para>0 - success</para></listitem>" << endl
|
||||
<< " <listitem><para>1 - error</para></listitem>" << endl
|
||||
<< " <listitem><para>2 - unsupported</para></listitem>" << endl
|
||||
<< " <listitem><para>3 - empty (command was completed successfully, but "
|
||||
<< "no data was affected or returned)</para>"
|
||||
<< "</listitem>" << endl
|
||||
<< "</itemizedlist>" << endl;
|
||||
return (t.str());
|
||||
}
|
||||
|
||||
/// @brief generates command description
|
||||
///
|
||||
/// @param f stream to write the description to
|
||||
/// @param cmd pointer to JSON structure that describes the command
|
||||
void generateCommand(stringstream& f, const ElementPtr& cmd) {
|
||||
|
||||
// command overview
|
||||
f << "<para xml:id=\"ref-" << cmd->get("name")->stringValue() << "\"><command>"
|
||||
<< cmd->get("name")->stringValue() << "</command> - "
|
||||
<< cmd->get("brief")->stringValue() << "</para>" << endl << endl;
|
||||
|
||||
// command can be issued to the following daemons
|
||||
f << "<para>Supported by: ";
|
||||
ConstElementPtr daemons = cmd->get("support");
|
||||
for (int i = 0; i < daemons->size(); i++) {
|
||||
if (i) {
|
||||
f << ", ";
|
||||
}
|
||||
|
||||
f << "<command><link linkend=\"commands-" << daemons->get(i)->stringValue()
|
||||
<< "\">" << daemons->get(i)->stringValue() << "</link></command>";
|
||||
}
|
||||
f << "</para>" << endl << endl;
|
||||
|
||||
// availability
|
||||
f << "<para>Availability: " << cmd->get("avail")->stringValue();
|
||||
auto hook = cmd->get("hook");
|
||||
if (hook) {
|
||||
f << " (<link linkend=\"commands-" << hook->stringValue() << "-lib\">"
|
||||
<< hook->stringValue() << "</link> hook)";
|
||||
} else {
|
||||
f << " (built-in)";
|
||||
}
|
||||
|
||||
f << "</para>" << endl << endl;
|
||||
|
||||
// description and examples
|
||||
f << "<para>Description and examples: See <xref linkend=\"command-"
|
||||
<< cmd->get("name")->stringValue() << "\"/></para>" << endl << endl;
|
||||
|
||||
// Command syntax:
|
||||
f << "<para>Command syntax:" << endl;
|
||||
if (cmd->contains("cmd-syntax")) {
|
||||
f << " <screen>" << escapeString(cmd->get("cmd-syntax")->stringValue())
|
||||
<< "</screen>" << endl;
|
||||
} else {
|
||||
f << " <screen>{" << endl
|
||||
<< " \"command\": \"" << cmd->get("name")->stringValue() << "\"" << endl
|
||||
<< "}</screen>" << endl;
|
||||
}
|
||||
if (cmd->contains("cmd-comment")) {
|
||||
f << cmd->get("cmd-comment")->stringValue();
|
||||
}
|
||||
f << "</para>" << endl << endl;
|
||||
|
||||
// Response syntax
|
||||
f << "<para>Response syntax:" << endl
|
||||
<< " <screen>";
|
||||
|
||||
if (cmd->contains("resp-syntax")) {
|
||||
f << escapeString(cmd->get("resp-syntax")->stringValue());
|
||||
} else {
|
||||
f << escapeString(standardResponseSyntax());
|
||||
}
|
||||
f << "</screen>" << endl;
|
||||
|
||||
if (cmd->contains("resp-comment")) {
|
||||
f << cmd->get("resp-comment")->stringValue();
|
||||
} else {
|
||||
f << standardResponseComment();
|
||||
}
|
||||
f << "</para>" << endl << endl;
|
||||
}
|
||||
|
||||
map<string, ElementPtr> cmds_;
|
||||
};
|
||||
|
||||
int main(int argc, const char*argv[]) {
|
||||
|
||||
vector<string> files;
|
||||
|
||||
for (int i = 1; i < argc; i++) {
|
||||
files.push_back(string(argv[i]));
|
||||
}
|
||||
|
||||
cout << "Loading " << files.size() << " files(s)." << endl;
|
||||
|
||||
try {
|
||||
DocGen doc_gen;
|
||||
|
||||
doc_gen.loadFiles(files);
|
||||
|
||||
doc_gen.generateOutput();
|
||||
} catch (const exception& e) {
|
||||
cerr << "ERROR: " << e.what() << endl;
|
||||
}
|
||||
|
||||
return (0);
|
||||
}
|
||||
@@ -20,6 +20,7 @@ static_sources+=static/kea.css
|
||||
|
||||
# ARM
|
||||
rst_arm_sources=
|
||||
rst_arm_sources+=arm/acknowledgments.rst
|
||||
rst_arm_sources+=arm/admin.rst
|
||||
rst_arm_sources+=arm/agent.rst
|
||||
rst_arm_sources+=arm/classify.rst
|
||||
@@ -46,10 +47,13 @@ rst_arm_sources+=arm/keactrl.rst
|
||||
rst_arm_sources+=arm/lease-expiration.rst
|
||||
rst_arm_sources+=arm/lfc.rst
|
||||
rst_arm_sources+=arm/logging.rst
|
||||
rst_arm_sources+=arm/manpages.rst
|
||||
rst_arm_sources+=arm/netconf.rst
|
||||
rst_arm_sources+=arm/quickstart.rst
|
||||
rst_arm_sources+=arm/shell.rst
|
||||
rst_arm_sources+=arm/stats.rst
|
||||
rst_arm_sources+=$(srcdir)/api.rst
|
||||
rst_arm_sources+=$(srcdir)/kea-messages.rst
|
||||
|
||||
main_sources=$(rst_arm_sources) conf.py $(static_sources)
|
||||
|
||||
@@ -61,18 +65,14 @@ rst_man_sources+=man/kea-dhcp4.8.rst
|
||||
rst_man_sources+=man/kea-dhcp6.8.rst
|
||||
rst_man_sources+=man/kea-dhcp-ddns.8.rst
|
||||
rst_man_sources+=man/kea-lfc.8.rst
|
||||
if HAVE_SYSREPO
|
||||
rst_man_sources+=man/kea-netconf.8.rst
|
||||
endif
|
||||
rst_man_sources+=man/kea-shell.8.rst
|
||||
rst_man_sources+=man/keactrl.8.rst
|
||||
if PERFDHCP
|
||||
rst_man_sources+=man/perfdhcp.8.rst
|
||||
endif
|
||||
man_sources=$(rst_man_sources) conf.py
|
||||
man8s=$(foreach rst,$(rst_man_sources), $(sphinxbuilddir)/$(basename $(rst)))
|
||||
|
||||
EXTRA_DIST += $(main_sources) $(man_sources) mes2doc.py
|
||||
EXTRA_DIST += $(main_sources) $(man_sources) api2doc.py mes2doc.py
|
||||
|
||||
|
||||
# list of messages files that are used to generate kea-messages.rst and then kea-messages.pdf
|
||||
@@ -101,152 +101,150 @@ mes_files+=$(top_srcdir)/src/bin/agent/ca_messages.mes
|
||||
mes_files+=$(top_srcdir)/src/bin/d2/d2_messages.mes
|
||||
mes_files+=$(top_srcdir)/src/bin/dhcp6/dhcp6_messages.mes
|
||||
mes_files+=$(top_srcdir)/src/bin/lfc/lfc_messages.mes
|
||||
if HAVE_SYSREPO
|
||||
mes_files+=$(top_srcdir)/src/bin/netconf/netconf_messages.mes
|
||||
endif
|
||||
|
||||
# list of api files that are used to generate api.rst
|
||||
api_files=
|
||||
api_files+=api/build-report.json
|
||||
api_files+=api/cache-clear.json
|
||||
api_files+=api/cache-get.json
|
||||
api_files+=api/cache-get-by-id.json
|
||||
api_files+=api/cache-insert.json
|
||||
api_files+=api/cache-load.json
|
||||
api_files+=api/cache-remove.json
|
||||
api_files+=api/cache-size.json
|
||||
api_files+=api/cache-write.json
|
||||
api_files+=api/class-add.json
|
||||
api_files+=api/class-del.json
|
||||
api_files+=api/class-get.json
|
||||
api_files+=api/class-list.json
|
||||
api_files+=api/class-update.json
|
||||
api_files+=api/config-get.json
|
||||
api_files+=api/config-reload.json
|
||||
api_files+=api/config-set.json
|
||||
api_files+=api/config-test.json
|
||||
api_files+=api/config-write.json
|
||||
api_files+=api/dhcp-disable.json
|
||||
api_files+=api/dhcp-enable.json
|
||||
api_files+=api/ha-continue.json
|
||||
api_files+=api/ha-heartbeat.json
|
||||
api_files+=api/ha-scopes.json
|
||||
api_files+=api/ha-sync.json
|
||||
api_files+=api/lease4-add.json
|
||||
api_files+=api/lease4-del.json
|
||||
api_files+=api/lease4-get-all.json
|
||||
api_files+=api/lease4-get.json
|
||||
api_files+=api/lease4-update.json
|
||||
api_files+=api/lease4-wipe.json
|
||||
api_files+=api/lease6-add.json
|
||||
api_files+=api/lease6-bulk-apply.json
|
||||
api_files+=api/lease6-del.json
|
||||
api_files+=api/lease6-get-all.json
|
||||
api_files+=api/lease6-get.json
|
||||
api_files+=api/lease6-update.json
|
||||
api_files+=api/lease6-wipe.json
|
||||
api_files+=api/leases-reclaim.json
|
||||
api_files+=api/libreload.json
|
||||
api_files+=api/list-commands.json
|
||||
api_files+=api/network4-add.json
|
||||
api_files+=api/network4-del.json
|
||||
api_files+=api/network4-get.json
|
||||
api_files+=api/network4-list.json
|
||||
api_files+=api/network4-subnet-add.json
|
||||
api_files+=api/network4-subnet-del.json
|
||||
api_files+=api/network6-add.json
|
||||
api_files+=api/network6-del.json
|
||||
api_files+=api/network6-get.json
|
||||
api_files+=api/network6-list.json
|
||||
api_files+=api/network6-subnet-add.json
|
||||
api_files+=api/network6-subnet-del.json
|
||||
api_files+=api/remote-global-parameter4-del.json
|
||||
api_files+=api/remote-global-parameter4-get-all.json
|
||||
api_files+=api/remote-global-parameter4-get.json
|
||||
api_files+=api/remote-global-parameter4-set.json
|
||||
api_files+=api/remote-global-parameter6-del.json
|
||||
api_files+=api/remote-global-parameter6-get-all.json
|
||||
api_files+=api/remote-global-parameter6-get.json
|
||||
api_files+=api/remote-global-parameter6-set.json
|
||||
api_files+=api/remote-network4-del.json
|
||||
api_files+=api/remote-network4-get.json
|
||||
api_files+=api/remote-network4-list.json
|
||||
api_files+=api/remote-network4-set.json
|
||||
api_files+=api/remote-network6-del.json
|
||||
api_files+=api/remote-network6-get.json
|
||||
api_files+=api/remote-network6-list.json
|
||||
api_files+=api/remote-network6-set.json
|
||||
api_files+=api/remote-option-def4-del.json
|
||||
api_files+=api/remote-option-def4-get-all.json
|
||||
api_files+=api/remote-option-def4-get.json
|
||||
api_files+=api/remote-option-def4-set.json
|
||||
api_files+=api/remote-option-def6-del.json
|
||||
api_files+=api/remote-option-def6-get-all.json
|
||||
api_files+=api/remote-option-def6-get.json
|
||||
api_files+=api/remote-option-def6-set.json
|
||||
api_files+=api/remote-option4-global-del.json
|
||||
api_files+=api/remote-option4-global-get-all.json
|
||||
api_files+=api/remote-option4-global-get.json
|
||||
api_files+=api/remote-option4-global-set.json
|
||||
api_files+=api/remote-option6-global-del.json
|
||||
api_files+=api/remote-option6-global-get-all.json
|
||||
api_files+=api/remote-option6-global-get.json
|
||||
api_files+=api/remote-option6-global-set.json
|
||||
api_files+=api/remote-subnet4-del-by-id.json
|
||||
api_files+=api/remote-subnet4-del-by-prefix.json
|
||||
api_files+=api/remote-subnet4-get-by-id.json
|
||||
api_files+=api/remote-subnet4-get-by-prefix.json
|
||||
api_files+=api/remote-subnet4-list.json
|
||||
api_files+=api/remote-subnet4-set.json
|
||||
api_files+=api/remote-subnet6-del-by-id.json
|
||||
api_files+=api/remote-subnet6-del-by-prefix.json
|
||||
api_files+=api/remote-subnet6-get-by-id.json
|
||||
api_files+=api/remote-subnet6-get-by-prefix.json
|
||||
api_files+=api/remote-subnet6-list.json
|
||||
api_files+=api/remote-subnet6-set.json
|
||||
api_files+=api/reservation-add.json
|
||||
api_files+=api/reservation-del.json
|
||||
api_files+=api/reservation-get.json
|
||||
api_files+=api/reservation-get-all.json
|
||||
api_files+=api/reservation-get-page.json
|
||||
api_files+=api/shutdown.json
|
||||
api_files+=api/statistic-get-all.json
|
||||
api_files+=api/statistic-get.json
|
||||
api_files+=api/statistic-remove-all.json
|
||||
api_files+=api/statistic-remove.json
|
||||
api_files+=api/statistic-reset-all.json
|
||||
api_files+=api/statistic-reset.json
|
||||
api_files+=api/stat-lease4-get.json
|
||||
api_files+=api/stat-lease6-get.json
|
||||
api_files+=api/subnet4-add.json
|
||||
api_files+=api/subnet4-del.json
|
||||
api_files+=api/subnet4-get.json
|
||||
api_files+=api/subnet4-list.json
|
||||
api_files+=api/subnet4-update.json
|
||||
api_files+=api/subnet6-add.json
|
||||
api_files+=api/subnet6-del.json
|
||||
api_files+=api/subnet6-get.json
|
||||
api_files+=api/subnet6-list.json
|
||||
api_files+=api/subnet6-update.json
|
||||
api_files+=api/version-get.json
|
||||
api_files+=$(srcdir)/api/build-report.json
|
||||
api_files+=$(srcdir)/api/cache-clear.json
|
||||
api_files+=$(srcdir)/api/cache-get.json
|
||||
api_files+=$(srcdir)/api/cache-get-by-id.json
|
||||
api_files+=$(srcdir)/api/cache-insert.json
|
||||
api_files+=$(srcdir)/api/cache-load.json
|
||||
api_files+=$(srcdir)/api/cache-remove.json
|
||||
api_files+=$(srcdir)/api/cache-size.json
|
||||
api_files+=$(srcdir)/api/cache-write.json
|
||||
api_files+=$(srcdir)/api/class-add.json
|
||||
api_files+=$(srcdir)/api/class-del.json
|
||||
api_files+=$(srcdir)/api/class-get.json
|
||||
api_files+=$(srcdir)/api/class-list.json
|
||||
api_files+=$(srcdir)/api/class-update.json
|
||||
api_files+=$(srcdir)/api/config-get.json
|
||||
api_files+=$(srcdir)/api/config-reload.json
|
||||
api_files+=$(srcdir)/api/config-set.json
|
||||
api_files+=$(srcdir)/api/config-test.json
|
||||
api_files+=$(srcdir)/api/config-write.json
|
||||
api_files+=$(srcdir)/api/dhcp-disable.json
|
||||
api_files+=$(srcdir)/api/dhcp-enable.json
|
||||
api_files+=$(srcdir)/api/ha-continue.json
|
||||
api_files+=$(srcdir)/api/ha-heartbeat.json
|
||||
api_files+=$(srcdir)/api/ha-scopes.json
|
||||
api_files+=$(srcdir)/api/ha-sync.json
|
||||
api_files+=$(srcdir)/api/lease4-add.json
|
||||
api_files+=$(srcdir)/api/lease4-del.json
|
||||
api_files+=$(srcdir)/api/lease4-get-all.json
|
||||
api_files+=$(srcdir)/api/lease4-get.json
|
||||
api_files+=$(srcdir)/api/lease4-update.json
|
||||
api_files+=$(srcdir)/api/lease4-wipe.json
|
||||
api_files+=$(srcdir)/api/lease6-add.json
|
||||
api_files+=$(srcdir)/api/lease6-bulk-apply.json
|
||||
api_files+=$(srcdir)/api/lease6-del.json
|
||||
api_files+=$(srcdir)/api/lease6-get-all.json
|
||||
api_files+=$(srcdir)/api/lease6-get.json
|
||||
api_files+=$(srcdir)/api/lease6-update.json
|
||||
api_files+=$(srcdir)/api/lease6-wipe.json
|
||||
api_files+=$(srcdir)/api/leases-reclaim.json
|
||||
api_files+=$(srcdir)/api/libreload.json
|
||||
api_files+=$(srcdir)/api/list-commands.json
|
||||
api_files+=$(srcdir)/api/network4-add.json
|
||||
api_files+=$(srcdir)/api/network4-del.json
|
||||
api_files+=$(srcdir)/api/network4-get.json
|
||||
api_files+=$(srcdir)/api/network4-list.json
|
||||
api_files+=$(srcdir)/api/network4-subnet-add.json
|
||||
api_files+=$(srcdir)/api/network4-subnet-del.json
|
||||
api_files+=$(srcdir)/api/network6-add.json
|
||||
api_files+=$(srcdir)/api/network6-del.json
|
||||
api_files+=$(srcdir)/api/network6-get.json
|
||||
api_files+=$(srcdir)/api/network6-list.json
|
||||
api_files+=$(srcdir)/api/network6-subnet-add.json
|
||||
api_files+=$(srcdir)/api/network6-subnet-del.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter4-del.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter4-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter4-get.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter4-set.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter6-del.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter6-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter6-get.json
|
||||
api_files+=$(srcdir)/api/remote-global-parameter6-set.json
|
||||
api_files+=$(srcdir)/api/remote-network4-del.json
|
||||
api_files+=$(srcdir)/api/remote-network4-get.json
|
||||
api_files+=$(srcdir)/api/remote-network4-list.json
|
||||
api_files+=$(srcdir)/api/remote-network4-set.json
|
||||
api_files+=$(srcdir)/api/remote-network6-del.json
|
||||
api_files+=$(srcdir)/api/remote-network6-get.json
|
||||
api_files+=$(srcdir)/api/remote-network6-list.json
|
||||
api_files+=$(srcdir)/api/remote-network6-set.json
|
||||
api_files+=$(srcdir)/api/remote-option-def4-del.json
|
||||
api_files+=$(srcdir)/api/remote-option-def4-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-option-def4-get.json
|
||||
api_files+=$(srcdir)/api/remote-option-def4-set.json
|
||||
api_files+=$(srcdir)/api/remote-option-def6-del.json
|
||||
api_files+=$(srcdir)/api/remote-option-def6-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-option-def6-get.json
|
||||
api_files+=$(srcdir)/api/remote-option-def6-set.json
|
||||
api_files+=$(srcdir)/api/remote-option4-global-del.json
|
||||
api_files+=$(srcdir)/api/remote-option4-global-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-option4-global-get.json
|
||||
api_files+=$(srcdir)/api/remote-option4-global-set.json
|
||||
api_files+=$(srcdir)/api/remote-option6-global-del.json
|
||||
api_files+=$(srcdir)/api/remote-option6-global-get-all.json
|
||||
api_files+=$(srcdir)/api/remote-option6-global-get.json
|
||||
api_files+=$(srcdir)/api/remote-option6-global-set.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-del-by-id.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-del-by-prefix.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-get-by-id.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-get-by-prefix.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-list.json
|
||||
api_files+=$(srcdir)/api/remote-subnet4-set.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-del-by-id.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-del-by-prefix.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-get-by-id.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-get-by-prefix.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-list.json
|
||||
api_files+=$(srcdir)/api/remote-subnet6-set.json
|
||||
api_files+=$(srcdir)/api/reservation-add.json
|
||||
api_files+=$(srcdir)/api/reservation-del.json
|
||||
api_files+=$(srcdir)/api/reservation-get.json
|
||||
api_files+=$(srcdir)/api/reservation-get-all.json
|
||||
api_files+=$(srcdir)/api/reservation-get-page.json
|
||||
api_files+=$(srcdir)/api/shutdown.json
|
||||
api_files+=$(srcdir)/api/statistic-get-all.json
|
||||
api_files+=$(srcdir)/api/statistic-get.json
|
||||
api_files+=$(srcdir)/api/statistic-remove-all.json
|
||||
api_files+=$(srcdir)/api/statistic-remove.json
|
||||
api_files+=$(srcdir)/api/statistic-reset-all.json
|
||||
api_files+=$(srcdir)/api/statistic-reset.json
|
||||
api_files+=$(srcdir)/api/stat-lease4-get.json
|
||||
api_files+=$(srcdir)/api/stat-lease6-get.json
|
||||
api_files+=$(srcdir)/api/subnet4-add.json
|
||||
api_files+=$(srcdir)/api/subnet4-del.json
|
||||
api_files+=$(srcdir)/api/subnet4-get.json
|
||||
api_files+=$(srcdir)/api/subnet4-list.json
|
||||
api_files+=$(srcdir)/api/subnet4-update.json
|
||||
api_files+=$(srcdir)/api/subnet6-add.json
|
||||
api_files+=$(srcdir)/api/subnet6-del.json
|
||||
api_files+=$(srcdir)/api/subnet6-get.json
|
||||
api_files+=$(srcdir)/api/subnet6-list.json
|
||||
api_files+=$(srcdir)/api/subnet6-update.json
|
||||
api_files+=$(srcdir)/api/version-get.json
|
||||
|
||||
EXTRA_DIST += $(api_files)
|
||||
|
||||
|
||||
all: html mans pdf
|
||||
|
||||
kea-messages.rst: $(mes_files) mes2doc.py
|
||||
$(srcdir)/kea-messages.rst: $(mes_files) mes2doc.py
|
||||
$(srcdir)/mes2doc.py -o $@ $(mes_files)
|
||||
|
||||
|
||||
api.rst: $(api_files) api2doc.py
|
||||
$(srcdir)/api.rst: $(api_files) api2doc.py
|
||||
$(srcdir)/api2doc.py -o $@ $(api_files)
|
||||
|
||||
|
||||
pdf: $(main_sources) api.rst kea-messages.rst
|
||||
pdf: $(main_sources)
|
||||
$(SPHINXBUILD) -M latexpdf $(srcdir) $(sphinxbuilddir) $(sphinxopts)
|
||||
|
||||
html: $(main_sources) api.rst kea-messages.rst
|
||||
html: $(main_sources)
|
||||
$(SPHINXBUILD) -M html $(srcdir) $(sphinxbuilddir) $(sphinxopts)
|
||||
|
||||
$(man8s): mans
|
||||
@@ -267,38 +265,9 @@ uninstall-local:
|
||||
|
||||
clean-local:
|
||||
rm -rf $(sphinxbuilddir)
|
||||
rm -f api.rst kea-messages.rst
|
||||
rm -f $(srcdir)/api.rst $(srcdir)/kea-messages.rst
|
||||
|
||||
.PHONY: all pdf html mans
|
||||
|
||||
|
||||
endif
|
||||
|
||||
# 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 generate
|
||||
# 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.
|
||||
templates: docgen
|
||||
docgen/generate-templates docgen/cmds-list
|
||||
|
||||
17
doc/sphinx/api/README
Normal file
17
doc/sphinx/api/README
Normal file
@@ -0,0 +1,17 @@
|
||||
There are several steps needed to document new API command:
|
||||
|
||||
1. edit cmds-list and add the new command
|
||||
2. (optional) run: ./generate-templates cmds-list
|
||||
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 _template.json
|
||||
and copy it over under the name of a new command.
|
||||
3. 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.
|
||||
4. Rebuild User's Guide as usual, run in doc/sphinx folder: make
|
||||
@@ -73,6 +73,7 @@ exclude_patterns = [
|
||||
# included files need to be excluded to avoid duplicate labels
|
||||
'arm/hooks-class-cmds.rst',
|
||||
'arm/hooks-cb-cmds.rst',
|
||||
'arm/config-backend.rst',
|
||||
'arm/hooks-ha.rst',
|
||||
'arm/hooks-host-cache.rst',
|
||||
'arm/hooks-lease-cmds.rst',
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-admin:
|
||||
|
||||
kea-admin - Shell script for managing Kea databases
|
||||
---------------------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-ctrl-agent:
|
||||
|
||||
kea-ctrl-agent - Control Agent process in Kea
|
||||
---------------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-dhcp-ddns:
|
||||
|
||||
kea-dhcp-ddns - DHCP-DDNS process in Kea
|
||||
----------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-dhcp4:
|
||||
|
||||
kea-dhcp4 - DHCPv4 server in Kea
|
||||
--------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-dhcp6:
|
||||
|
||||
kea-dhcp6 - DHCPv6 server in Kea
|
||||
--------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-lfc:
|
||||
|
||||
kea-lfc - Lease File Cleanup process in Kea
|
||||
-------------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-netconf:
|
||||
|
||||
kea-netconf - NETCONF agent for Kea environment
|
||||
-----------------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. kea-shell:
|
||||
|
||||
kea-shell - Text client for Control Agent process
|
||||
-------------------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. _keactrl:
|
||||
|
||||
keactrl - Shell script for managing Kea
|
||||
---------------------------------------
|
||||
|
||||
@@ -8,9 +8,6 @@
|
||||
See the COPYRIGHT file distributed with this work for additional
|
||||
information regarding copyright ownership.
|
||||
|
||||
.. highlight: console
|
||||
|
||||
.. _perfdhcp:
|
||||
|
||||
perfdhcp - DHCP benchmarking tool
|
||||
---------------------------------
|
||||
|
||||
@@ -1 +0,0 @@
|
||||
<!ENTITY keaversion "@PACKAGE_VERSION@">
|
||||
Reference in New Issue
Block a user