From: Gervase Markham Date: Wed, 26 Nov 2014 16:44:56 +0000 (+0000) Subject: Merge branch 'master' of ssh://git.mozilla.org/bugzilla/bugzilla into docs-relicensin... X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=8463a3c10b4d56476c61740b7088d36d3f0b55b6;p=thirdparty%2Fbugzilla.git Merge branch 'master' of ssh://git.mozilla.org/bugzilla/bugzilla into docs-relicensing, including new REST API docs from dkl. Conflicts: docs/en/rst/extensions.rst docs/en/rst/index.rst docs/en/rst/installation.rst --- 8463a3c10b4d56476c61740b7088d36d3f0b55b6 diff --cc .gitignore index dae5208fc6,f30e8f9ae1..89d5bdf35b --- a/.gitignore +++ b/.gitignore @@@ -1,7 -1,6 +1,8 @@@ .htaccess /lib/* /template/en/custom +/docs/en/rst/extensions/* ++/docs/en/rst/api/extensions/* /docs/en/html /docs/en/txt /docs/en/pdf diff --cc docs/en/rst/api/index.rst index 0000000000,99cb94c6d0..55c997a68c mode 000000,100644..100644 --- a/docs/en/rst/api/index.rst +++ b/docs/en/rst/api/index.rst @@@ -1,0 -1,11 +1,13 @@@ -WebService API -============== ++.. _apis: ++ ++WebService API Reference ++======================== + + This Bugzilla installation has the following WebService APIs available + (as of the last time you compiled the documentation): + + .. toctree:: + :glob: + - api/core/v*/index* - api/extensions/*/v*/index* ++ core/v*/index* ++ extensions/*/v*/index* diff --cc docs/en/rst/index.rst index e95560e8e0,2da16e2234..b877920c64 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@@ -3,28 -7,18 +3,29 @@@ Bugzilla Documentatio ====================== .. toctree:: - :maxdepth: 3 - :numbered: + :maxdepth: 1 + :numbered: 4 + + about/index + using/index + installing/index + administering/index + integrating/index - ++ api/index ++ +.. toctree:: + :hidden: + + installing/mysql + installing/postgresql + installing/oracle + installing/sqlite + +.. toctree:: + :hidden: + + installing/apache + installing/apache-windows + installing/iis - about - installation - administration - security - using - extensions - api - customization - patches - troubleshooting - modules - gfdl +.. todolist:: diff --cc docs/en/rst/integrating/apis.rst index ee5e230de8,0000000000..6067c12dff mode 100644,000000..100644 --- a/docs/en/rst/integrating/apis.rst +++ b/docs/en/rst/integrating/apis.rst @@@ -1,74 -1,0 +1,72 @@@ - .. _apis: ++.. _api-list: + +APIs +#### + +Bugzilla has a number of APIs that you can call in your code to extract +information from and put information into Bugzilla. Some are deprecated and +will soon be removed. Which one to use? Short answer: the - `REST API - `_ ++:ref:`REST WebService API v1 ` +should be used for all new integrations, but keep an eye out for version 2, +coming soon. + +The APIs currently available are as follows: + +Ad-Hoc APIs +=========== + +Various pages on Bugzilla are available in machine-parseable formats as well +as HTML. For example, bugs can be downloaded as XML, and buglists as CSV. +CSV is useful for spreadsheet import. There should be links on the HTML page +to alternate data formats where they are available. + +XML-RPC +======= + +Bugzilla has an `XML-RPC API +`_. +This will receive no further updates and will be removed in a future version +of Bugzilla. + +Endpoint: :file:`/xmlrpc.cgi` + +JSON-RPC +======== + +Bugzilla has a `JSON-RPC API +`_. +This will receive no further updates and will be removed in a future version +of Bugzilla. + +Endpoint: :file:`/jsonrpc.cgi` + +REST +==== + - Bugzilla has a `REST API - `_ - which is the currently-recommended API for integrating with Bugzilla. The - current REST API is version 1. It is stable, and so will not be changed in a - backwardly-incompatible way. **This is the currently-recommended API for - new development.** ++Bugzilla has a :ref:`REST API ` which is the currently-recommended API ++for integrating with Bugzilla. The current REST API is version 1. It is stable, ++and so will not be changed in a backwardly-incompatible way. ++ ++**This is the currently-recommended API for new development.** + +Endpoint: :file:`/rest` + +BzAPI/BzAPI-Compatible REST +=========================== + +The first ever REST API for Bugzilla was implemented using an external proxy +called `BzAPI `_. This became popular +enough that a BzAPI-compatible shim on top of the (native) REST API has been +written, to allow code which used the BzAPI API to take advantage of the +speed improvements of direct integration without needing to be rewritten. +The shim is an extension which you would need to install in your Bugzilla. + +Neither BzAPI nor this BzAPI-compatible API shim will receive any further +updates, and they should not be used for new code. + +REST v2 +======= + +The future of Bugzilla's APIs is version 2 of the REST API, which will take +the best of the current REST API and the BzAPI API. It is still under +development. diff --cc docs/makedocs.pl index 4f0f52579d,be55730808..a588484034 --- a/docs/makedocs.pl +++ b/docs/makedocs.pl @@@ -138,11 -146,25 +146,26 @@@ foreach my $lang (@langs) # Clear out old extensions docs rmtree('rst/extensions', 0, 1); mkdir('rst/extensions'); - - find({ - 'wanted' => \&wanted, - 'no_chdir' => 1, - }, "$docparent/../extensions"); + rmtree('rst/api/extensions', 0, 1); + mkdir('rst/api/extensions'); + + foreach my $ext_name (keys %extensions) { + foreach my $path (glob($extensions{$ext_name} . "/*")) { + my ($file, $dir) = fileparse($path); + if ($file eq 'api') { + my $dst = "$docparent/$lang/rst/api/extensions/$ext_name"; + mkdir($dst) unless -d $dst; + rcopy("$path/*", $dst); - next; + } - my $dst = "$docparent/$lang/rst/extensions/$ext_name"; - mkdir($dst) unless -d $dst; - rcopy($path, "$dst/$file"); ++ else { ++ my $dst = "$docparent/$lang/rst/extensions/$ext_name"; ++ mkdir($dst) unless -d $dst; ++ rcopy($path, "$dst/$file"); ++ } + } + } + + chdir "$docparent/$lang"; MakeDocs('HTML', 'make html'); MakeDocs('TXT', 'make text');