Bug 963120 - allow extensions to document themselves, and build result into docs. r=LpSolit, a=justdave.

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) {