Bug 1038275: Comprehensible documentation for the REST API

r=gerv,a=glob

2 files changed, 25 insertions, 0 deletions

diff --git a/extensions/Example/docs/en/rst/api/v1/index.rst b/extensions/Example/docs/en/rst/api/v1/index.rst
new file mode 100644
index 000000000..02186bb0b
--- /dev/null
+++ b/extensions/Example/docs/en/rst/api/v1/index.rst
@@ -0,0 +1,4 @@
+Example API v1
+==============
+
+Here is where you place your API docs for the Example extension.
diff --git a/extensions/Example/docs/en/rst/example.rst b/extensions/Example/docs/en/rst/example.rst
new file mode 100644
index 000000000..f2c055bae
--- /dev/null
+++ b/extensions/Example/docs/en/rst/example.rst
@@ -0,0 +1,21 @@
+Example
+#######
+
+This is a sample documentation file for the Example extension. Like all of
+the Bugzilla docs, it's written in
+`reStructured Text (reST) format <http://sphinx-doc.org/latest/rest.html>`_
+and will be compiled by `Sphinx <http://sphinx-doc.org/>`_.
+
+If you build the docs yourself using :file:`makedocs.pl`, this file will get
+incorporated into the Extensions chapter, as will any documentation
+you write for your extensions which fulfils the following criteria:
+
+* In the :file:`extensions/YourExtension/doc/` directory
+* Has a :file:`.rst` file extension
+
+You are recommended to make the name of your reST doc file the same as the
+name of your extension, so that there is no clash when all the extension
+documentation is copied into the same directory. So, for example, this file
+is called :file:`example.rst`, as it's part of the Example extension. If you
+need multiple documentation files, prefix the filename with the name of your
+extension, e.g. :file:`example-extra.rst`.