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

7 files changed, 81 insertions, 3 deletions

diff --git a/docs/en/rst/extensions.rst b/docs/en/rst/extensions.rst
new file mode 100644
index 000000000..91eaab952
--- /dev/null
+++ b/docs/en/rst/extensions.rst
@@ -0,0 +1,11 @@
+Extensions
+==========
+
+Your Bugzilla installation has the following extensions available (as of the
+last time you compiled the documentation):
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   
+   extensions/*
diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index abb63d0ee..f2bd14f18 100644
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -15,8 +15,9 @@ Bugzilla Documentation
    administration
    security
    using
+   extensions
    customization
-   troubleshooting
    patches
+   troubleshooting
    modules
    gfdl
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index deb117ff3..d14e79434 100755
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -25,6 +25,8 @@ use 5.10.1;
 use strict;
 
 use Cwd;
+use File::Find;
+use File::Copy;
 
 # We need to be in this directory to use our libraries.
 BEGIN {
@@ -122,6 +124,24 @@ foreach my $lang (@langs) {
 
     next if grep { $_ eq '--pod-only' } @ARGV;
 
+    # Collect up local extension documentation into the extensions/ dir.
+    sub wanted {
+        if ($File::Find::dir =~ /\/doc\/?$/ &&
+            $_ =~ /\.rst$/)
+        {
+            copy($File::Find::name, "rst/extensions");
+        }
+    };
+
+    # Clear out old extensions docs
+    rmtree('rst/extensions', 0, 1);
+    mkdir('rst/extensions');
+    
+    find({
+        'wanted' => \&wanted,
+        'no_chdir' => 1,
+    }, "$docparent/../extensions");
+
     MakeDocs('HTML', 'make html');
     MakeDocs('TXT', 'make text');
 
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) {
diff --git a/t/008filter.t b/t/008filter.t
index 4977658bb..9551ae2b2 100644
--- a/t/008filter.t
+++ b/t/008filter.t
@@ -80,7 +80,7 @@ foreach my $path (@Support::Templates::include_paths) {
     foreach my $file (@testitems) {
         # There are some files we don't check, because there is no need to
         # filter their contents due to their content-type.
-        if ($file =~ /\.(pm|txt|png)\.tmpl$/) {
+        if ($file =~ /\.(pm|txt|rst|png)\.tmpl$/) {
             ok(1, "($lang/$flavor) $file is filter-safe");
             next;
         }
diff --git a/template/en/default/extensions/name.rst.tmpl b/template/en/default/extensions/name.rst.tmpl
new file mode 100644
index 000000000..c2e1b5a80
--- /dev/null
+++ b/template/en/default/extensions/name.rst.tmpl
@@ -0,0 +1,23 @@
+[%# This Source Code Form is subject to the terms of the Mozilla Public
+  # License, v. 2.0. If a copy of the MPL was not distributed with this
+  # file, You can obtain one at http://mozilla.org/MPL/2.0/.
+  #
+  # This Source Code Form is "Incompatible With Secondary Licenses", as
+  # defined by the Mozilla Public License, v. 2.0.
+  #%]
+
+[%# INTERFACE:
+  # name: string; the name of the extension.
+  #%]
+
+[% USE String('#') %]
+[% name %]
+[%+ String.repeat(name.length) %]
+
+This is a sample documentation file for the [% name %] 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.