Bug 963120 - allow extensions to document themselves, and build result into…

docs/en/rst/extensions.rst

+Extensions
+==========
+
+Your Bugzilla installation has the following extensions available (as of the
+last time you compiled the documentation):
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   
+   extensions/*

docs/en/rst/index.rst

@@ -15,8 +15,9 @@ Bugzilla Documentation
    administration
    security
    using
+   extensions
    customization
-   troubleshooting
    patches
+   troubleshooting
    modules
    gfdl

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');
 

extensions/Example/doc/example.rst

+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`.
+ 

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

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;
         }

template/en/default/extensions/name.rst.tmpl

+[%# 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.