summaryrefslogtreecommitdiffstats
path: root/extensions
diff options
context:
space:
mode:
authorGervase Markham <gerv@gerv.net>2014-02-25 13:00:48 +0100
committerGervase Markham <gerv@mozilla.org>2014-02-25 13:00:48 +0100
commit34477d3793d308de20711a4df48f7823c91baaba (patch)
tree28da01ac0931a0f5858e9a793fa1a32f975a723c /extensions
parentef925d6942a3462a9c1d52406a6145b5e31faefb (diff)
downloadbugzilla-34477d3793d308de20711a4df48f7823c91baaba.tar.gz
bugzilla-34477d3793d308de20711a4df48f7823c91baaba.tar.xz
Bug 963120 - allow extensions to document themselves, and build result into docs. r=LpSolit, a=justdave.
Diffstat (limited to 'extensions')
-rw-r--r--extensions/Example/doc/example.rst22
-rwxr-xr-xextensions/create.pl3
2 files changed, 24 insertions, 1 deletions
diff --git a/extensions/Example/doc/example.rst b/extensions/Example/doc/example.rst
new file mode 100644
index 000000000..07b355887
--- /dev/null
+++ b/extensions/Example/doc/example.rst
@@ -0,0 +1,22 @@
+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`.
+
diff --git a/extensions/create.pl b/extensions/create.pl
index e5a436845..e2d3321b1 100755
--- a/extensions/create.pl
+++ b/extensions/create.pl
@@ -30,7 +30,7 @@ mkpath($extension_dir)
|| die "$extension_dir already exists or cannot be created.\n";
my $lcname = lc($name);
-foreach my $path (qw(lib web template/en/default/hook),
+foreach my $path (qw(lib doc web template/en/default/hook),
"template/en/default/$lcname")
{
mkpath("$extension_dir/$path") || die "$extension_dir/$path: $!";
@@ -45,6 +45,7 @@ my %create_files = (
'web-readme.txt.tmpl' => 'web/README',
'hook-readme.txt.tmpl' => 'template/en/default/hook/README',
'name-readme.txt.tmpl' => "template/en/default/$lcname/README",
+ 'name.rst.tmpl' => "doc/$lcname.rst",
);
foreach my $template_file (keys %create_files) {