system-software-updates.adoc \
sysadmin.adoc
+API_VIEWER_SOURCES= \
+ api-viewer/index.html \
+ api-viewer/apidoc.js
+
PVE_ADMIN_GUIDE_SOURCES= \
${DATACENTER_CONF_MAN5_SOURCES} \
${QM_CONF_MAN5_SOURCES} \
asciidoc ${ADOC_MAN5_HTML_ARGS} -o $@ $*.adoc
test -n "$${NOVIEW}" || $(BROWSER) $@ &
-index.html: index.adoc ${PVE_ADMIN_GUIDE_SOURCES}
+index.html: index.adoc ${PVE_ADMIN_GUIDE_SOURCES} ${API_VIEWER_SOURCES}
$(MAKE) NOVIEW=1 pve-admin-guide.pdf pve-admin-guide.html pve-admin-guide.epub
$(MAKE) NOVIEW=1 $(addsuffix .1.html, ${COMMAND_LIST}) $(addsuffix .8.html, ${SERVICE_LIST}) $(addsuffix .5.html, ${CONFIG_LIST})
asciidoc -a "date=$(shell date)" -a "revnumber=${DOCRELEASE}" index.adoc
a2x -f epub pve-admin-guide.adoc
test -n "$${NOVIEW}" || $(BROWSER) $@ &
-apidata.js: extractapi.pl
+api-viewer/apidata.js: extractapi.pl
./extractapi.pl >$@
-apidoc.js: apidata.js PVEAPI.js
- cat apidata.js PVEAPI.js >$@
+api-viewer/apidoc.js: api-viewer/apidata.js api-viewer/PVEAPI.js
+ cat api-viewer/apidata.js api-viewer/PVEAPI.js >$@
.PHONY: dinstall
dinstall: ${GEN_DEB}
pve-admin-guide.epub \
index.html
-${DOC_DEB}: index.adoc ${PVE_ADMIN_GUIDE_SOURCES} apidoc.js apidoc.htm
+${DOC_DEB}: index.adoc ${PVE_ADMIN_GUIDE_SOURCES} ${API_VIEWER_SOURCES}
$(MAKE) NOVIEW=1 pve-admin-guide.pdf pve-admin-guide.html pve-admin-guide.epub
$(MAKE) NOVIEW=1 $(addsuffix .1.html, ${COMMAND_LIST}) $(addsuffix .8.html, ${SERVICE_LIST}) $(addsuffix .5.html, ${CONFIG_LIST})
asciidoc -a "date=$(shell date)" -a "revnumber=${DOCRELEASE}" index.adoc
echo "git clone git://git.proxmox.com/git/pve-docs.git\\ngit checkout ${GITVERSION}" > build/usr/share/doc/${DOC_PACKAGE}/SOURCE
# install doc files
install -m 0644 ${DOC_DEB_FILES} build/usr/share/${DOC_PACKAGE}
- install -m 0644 index.html build/usr/share/${DOC_PACKAGE}
# install api doc viewer
- mkdir build/usr/share/${DOC_PACKAGE}/pve2-api-doc
- install -m 0644 apidoc.htm build/usr/share/${DOC_PACKAGE}/pve2-api-doc/index.html
- install -m 0644 apidoc.js build/usr/share/${DOC_PACKAGE}/pve2-api-doc/
+ mkdir build/usr/share/${DOC_PACKAGE}/api-viewer
+ install -m 0644 ${API_VIEWER_SOURCES} build/usr/share/${DOC_PACKAGE}/api-viewer
cd build; dpkg-buildpackage -rfakeroot -b -us -uc
lintian ${DOC_DEB}
make all
clean:
- rm -rf *~ *.html *.pdf *.epub *.tmp *.1 *.5 *.8 *.deb *.changes build apidata.js apidoc.js
+ rm -rf *~ *.html *.pdf *.epub *.tmp *.1 *.5 *.8 *.deb *.changes build api-viewer/apidata.js api-viewer/apidoc.js
+++ /dev/null
-// avoid errors when running without development tools
-if (!Ext.isDefined(Ext.global.console)) {
- var console = {
- dir: function() {},
- log: function() {}
- };
-}
-
-Ext.onReady(function() {
-
- Ext.define('pve-param-schema', {
- extend: 'Ext.data.Model',
- fields: [
- 'name', 'type', 'typetext', 'description', 'enum',
- 'minimum', 'maximum', 'minLength', 'maxLength',
- 'pattern', 'title', 'requires', 'format', 'default',
- 'disallow', 'extends', 'links',
- {
- name: 'optional',
- type: 'boolean'
- }
- ]
- });
-
- var store = Ext.create('Ext.data.TreeStore', {
- model: Ext.define('pve-api-doc', {
- extend: 'Ext.data.Model',
- fields: [
- 'path', 'info', 'text',
- ]
- }),
- proxy: {
- type: 'memory',
- data: pveapi
- },
- sorters: [{
- property: 'leaf',
- direction: 'ASC'
- }, {
- property: 'text',
- direction: 'ASC'
- }]
- });
-
- var render_text = function(value, metaData, record) {
- var pdef = record.data;
-
- metaData.style = 'white-space:pre-wrap;'
-
- return Ext.htmlEncode(value);
- };
-
- var render_type = function(value, metaData, record) {
- var pdef = record.data;
-
- return pdef['enum'] ? 'enum' : (pdef.type || 'string');
- };
-
- var render_format = function(value, metaData, record) {
- var pdef = record.data;
-
- metaData.style = 'white-space:normal;'
-
- if (pdef.typetext)
- return pdef.typetext;
-
- if (pdef['enum'])
- return pdef['enum'].join(' | ');
-
- if (pdef.format)
- return pdef.format;
-
- if (pdef.pattern)
- return pdef.pattern;
-
- return '';
- };
-
- var render_docu = function(data) {
- var md = data.info;
-
- // console.dir(data);
-
- var items = [];
-
- var clicmdhash = {
- GET: 'get',
- POST: 'create',
- PUT: 'set',
- DELETE: 'delete'
- };
-
- Ext.Array.each(['GET', 'POST', 'PUT', 'DELETE'], function(method) {
- var info = md[method];
- if (info) {
-
- var usage = "";
-
- usage += "<table><tr><td>HTTP: </td><td>" + method + " /api2/json" + data.path + "</td></tr><tr><td> </td></tr>";
- usage += "<tr><td>CLI:</td><td>pvesh " + clicmdhash[method] + " " + data.path + "</td></tr></table>";
-
- var sections = [
- {
- title: 'Description',
- html: Ext.htmlEncode(info.description),
- bodyPadding: 10
- },
- {
- title: 'Usage',
- html: usage,
- bodyPadding: 10
- }
- ];
-
- if (info.parameters && info.parameters.properties) {
-
- var pstore = Ext.create('Ext.data.Store', {
- model: 'pve-param-schema',
- proxy: {
- type: 'memory'
- },
- groupField: 'optional',
- sorters: [
- {
- property: 'name',
- direction: 'ASC'
- }
- ]
- });
-
- Ext.Object.each(info.parameters.properties, function(name, pdef) {
- pdef.name = name;
- pstore.add(pdef);
- });
-
- pstore.sort();
-
- var groupingFeature = Ext.create('Ext.grid.feature.Grouping',{
- enableGroupingMenu: false,
- groupHeaderTpl: '<tpl if="name">Optional</tpl><tpl if="!name">Required</tpl>'
- });
-
- sections.push({
- xtype: 'gridpanel',
- title: 'Parameters',
- features: [groupingFeature],
- store: pstore,
- viewConfig: {
- trackOver: false,
- stripeRows: true
- },
- columns: [
- {
- header: 'Name',
- dataIndex: 'name'
- },
- {
- header: 'Type',
- dataIndex: 'type',
- renderer: render_type,
- },
- {
- header: 'Format',
- dataIndex: 'type',
- renderer: render_format,
- flex: 1
- },
- {
- header: 'Description',
- dataIndex: 'description',
- renderer: render_text,
- flex: 2
- }
- ]
- });
-
- }
-
- if (info.returns) {
-
- var rtype = info.returns.type;
- if (!rtype && info.returns.items)
- rtype = 'array';
- if (!rtype)
- rtype = 'object';
-
- sections.push({
- title: 'Returns: ' + rtype
- });
- }
-
- var permhtml = '';
- if (!info.permissions) {
- permhtml = "Root only.";
- } else {
- if (info.permissions.description) {
- permhtml += "<div style='white-space:pre-wrap;padding-bottom:10px;'>" +
- Ext.htmlEncode(info.permissions.description) + "</div>";
- }
-
- if (info.permissions.user) {
- if (!info.permissions.description) {
- if (info.permissions.user === 'world') {
- permhtml += "Accessible without any authententification.";
- } else if (info.permissions.user === 'all') {
- permhtml += "Accessible by all authententicated users.";
- } else {
- permhtml += 'Onyl accessible by user "' +
- info.permissions.user + '"';
- }
- }
- } else if (info.permissions.check) {
- permhtml += "<pre>Check: " +
- Ext.htmlEncode(Ext.JSON.encode(info.permissions.check)) + "</pre>";
- } else {
- permhtml += "Unknown systax!";
- }
- }
-
- sections.push({
- title: 'Required permissions',
- bodyPadding: 10,
- html: permhtml
- });
-
-
- items.push({
- title: method,
- autoScroll: true,
- defaults: {
- border: false
- },
- items: sections
- });
- }
- });
-
- var ct = Ext.getCmp('docview');
- ct.setTitle("Path: " + data.path);
- ct.removeAll(true);
- ct.add(items);
- };
-
- var tree = Ext.create('Ext.tree.Panel', {
- title: 'Resource Tree',
- store: store,
- width: 200,
- region: 'west',
- split: true,
- margins: '5 0 5 5',
- rootVisible: false,
- listeners: {
- selectionchange: function(v, selections) {
- if (!selections[0])
- return;
- var rec = selections[0];
- render_docu(rec.data);
- }
- }
- });
-
- Ext.create('Ext.container.Viewport', {
- layout: 'border',
- renderTo: Ext.getBody(),
- items: [
- tree,
- {
- xtype: 'tabpanel',
- title: 'Documentation',
- id: 'docview',
- region: 'center',
- margins: '5 5 5 0',
- layout: 'fit',
- items: []
- }
- ]
- });
-
-});
--- /dev/null
+// avoid errors when running without development tools
+if (!Ext.isDefined(Ext.global.console)) {
+ var console = {
+ dir: function() {},
+ log: function() {}
+ };
+}
+
+Ext.onReady(function() {
+
+ Ext.define('pve-param-schema', {
+ extend: 'Ext.data.Model',
+ fields: [
+ 'name', 'type', 'typetext', 'description', 'enum',
+ 'minimum', 'maximum', 'minLength', 'maxLength',
+ 'pattern', 'title', 'requires', 'format', 'default',
+ 'disallow', 'extends', 'links',
+ {
+ name: 'optional',
+ type: 'boolean'
+ }
+ ]
+ });
+
+ var store = Ext.create('Ext.data.TreeStore', {
+ model: Ext.define('pve-api-doc', {
+ extend: 'Ext.data.Model',
+ fields: [
+ 'path', 'info', 'text',
+ ]
+ }),
+ proxy: {
+ type: 'memory',
+ data: pveapi
+ },
+ sorters: [{
+ property: 'leaf',
+ direction: 'ASC'
+ }, {
+ property: 'text',
+ direction: 'ASC'
+ }]
+ });
+
+ var render_text = function(value, metaData, record) {
+ var pdef = record.data;
+
+ metaData.style = 'white-space:pre-wrap;'
+
+ return Ext.htmlEncode(value);
+ };
+
+ var render_type = function(value, metaData, record) {
+ var pdef = record.data;
+
+ return pdef['enum'] ? 'enum' : (pdef.type || 'string');
+ };
+
+ var render_format = function(value, metaData, record) {
+ var pdef = record.data;
+
+ metaData.style = 'white-space:normal;'
+
+ if (pdef.typetext)
+ return pdef.typetext;
+
+ if (pdef['enum'])
+ return pdef['enum'].join(' | ');
+
+ if (pdef.format)
+ return pdef.format;
+
+ if (pdef.pattern)
+ return pdef.pattern;
+
+ return '';
+ };
+
+ var render_docu = function(data) {
+ var md = data.info;
+
+ // console.dir(data);
+
+ var items = [];
+
+ var clicmdhash = {
+ GET: 'get',
+ POST: 'create',
+ PUT: 'set',
+ DELETE: 'delete'
+ };
+
+ Ext.Array.each(['GET', 'POST', 'PUT', 'DELETE'], function(method) {
+ var info = md[method];
+ if (info) {
+
+ var usage = "";
+
+ usage += "<table><tr><td>HTTP: </td><td>" + method + " /api2/json" + data.path + "</td></tr><tr><td> </td></tr>";
+ usage += "<tr><td>CLI:</td><td>pvesh " + clicmdhash[method] + " " + data.path + "</td></tr></table>";
+
+ var sections = [
+ {
+ title: 'Description',
+ html: Ext.htmlEncode(info.description),
+ bodyPadding: 10
+ },
+ {
+ title: 'Usage',
+ html: usage,
+ bodyPadding: 10
+ }
+ ];
+
+ if (info.parameters && info.parameters.properties) {
+
+ var pstore = Ext.create('Ext.data.Store', {
+ model: 'pve-param-schema',
+ proxy: {
+ type: 'memory'
+ },
+ groupField: 'optional',
+ sorters: [
+ {
+ property: 'name',
+ direction: 'ASC'
+ }
+ ]
+ });
+
+ Ext.Object.each(info.parameters.properties, function(name, pdef) {
+ pdef.name = name;
+ pstore.add(pdef);
+ });
+
+ pstore.sort();
+
+ var groupingFeature = Ext.create('Ext.grid.feature.Grouping',{
+ enableGroupingMenu: false,
+ groupHeaderTpl: '<tpl if="name">Optional</tpl><tpl if="!name">Required</tpl>'
+ });
+
+ sections.push({
+ xtype: 'gridpanel',
+ title: 'Parameters',
+ features: [groupingFeature],
+ store: pstore,
+ viewConfig: {
+ trackOver: false,
+ stripeRows: true
+ },
+ columns: [
+ {
+ header: 'Name',
+ dataIndex: 'name'
+ },
+ {
+ header: 'Type',
+ dataIndex: 'type',
+ renderer: render_type,
+ },
+ {
+ header: 'Format',
+ dataIndex: 'type',
+ renderer: render_format,
+ flex: 1
+ },
+ {
+ header: 'Description',
+ dataIndex: 'description',
+ renderer: render_text,
+ flex: 2
+ }
+ ]
+ });
+
+ }
+
+ if (info.returns) {
+
+ var rtype = info.returns.type;
+ if (!rtype && info.returns.items)
+ rtype = 'array';
+ if (!rtype)
+ rtype = 'object';
+
+ sections.push({
+ title: 'Returns: ' + rtype
+ });
+ }
+
+ var permhtml = '';
+ if (!info.permissions) {
+ permhtml = "Root only.";
+ } else {
+ if (info.permissions.description) {
+ permhtml += "<div style='white-space:pre-wrap;padding-bottom:10px;'>" +
+ Ext.htmlEncode(info.permissions.description) + "</div>";
+ }
+
+ if (info.permissions.user) {
+ if (!info.permissions.description) {
+ if (info.permissions.user === 'world') {
+ permhtml += "Accessible without any authententification.";
+ } else if (info.permissions.user === 'all') {
+ permhtml += "Accessible by all authententicated users.";
+ } else {
+ permhtml += 'Onyl accessible by user "' +
+ info.permissions.user + '"';
+ }
+ }
+ } else if (info.permissions.check) {
+ permhtml += "<pre>Check: " +
+ Ext.htmlEncode(Ext.JSON.encode(info.permissions.check)) + "</pre>";
+ } else {
+ permhtml += "Unknown systax!";
+ }
+ }
+
+ sections.push({
+ title: 'Required permissions',
+ bodyPadding: 10,
+ html: permhtml
+ });
+
+
+ items.push({
+ title: method,
+ autoScroll: true,
+ defaults: {
+ border: false
+ },
+ items: sections
+ });
+ }
+ });
+
+ var ct = Ext.getCmp('docview');
+ ct.setTitle("Path: " + data.path);
+ ct.removeAll(true);
+ ct.add(items);
+ };
+
+ var tree = Ext.create('Ext.tree.Panel', {
+ title: 'Resource Tree',
+ store: store,
+ width: 200,
+ region: 'west',
+ split: true,
+ margins: '5 0 5 5',
+ rootVisible: false,
+ listeners: {
+ selectionchange: function(v, selections) {
+ if (!selections[0])
+ return;
+ var rec = selections[0];
+ render_docu(rec.data);
+ }
+ }
+ });
+
+ Ext.create('Ext.container.Viewport', {
+ layout: 'border',
+ renderTo: Ext.getBody(),
+ items: [
+ tree,
+ {
+ xtype: 'tabpanel',
+ title: 'Documentation',
+ id: 'docview',
+ region: 'center',
+ margins: '5 5 5 0',
+ layout: 'fit',
+ items: []
+ }
+ ]
+ });
+
+});
--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<html>
+<head>
+<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
+ <title>Proxmox VE API Documentation</title>
+ <link rel="stylesheet" type="text/css" href="http://extjs.cachefly.net/ext-4.0.2/resources/css/ext-all.css" />
+
+ <script type="text/javascript" src="http://extjs.cachefly.net/ext-4.0.2/ext-all-debug.js"></script>
+ <script type="text/javascript" src="apidoc.js"></script>
+
+</head>
+<body>
+</body>
+</html>
+++ /dev/null
-<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
-<html>
-<head>
-<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
- <title>Proxmox VE API Documentation</title>
- <link rel="stylesheet" type="text/css" href="http://extjs.cachefly.net/ext-4.0.2/resources/css/ext-all.css" />
-
- <script type="text/javascript" src="http://extjs.cachefly.net/ext-4.0.2/ext-all-debug.js"></script>
- <script type="text/javascript" src="apidoc.js"></script>
-
-</head>
-<body>
-</body>
-</html>
</Directory>
Alias /pve-docs /usr/share/pve-docs/
-
-Alias /pve2-api-doc /usr/share/pve-docs/pve2-api-doc/
-
|===========================================================
+API Viewer
+~~~~~~~~~~
+
+The link:api-viewer/index.html[API viewer] is a tiny web application
+which allows you to inspect all available API calls.