Bug 1107549 - split extension docs into User and Admin docs. r=dkl, a=glob.

9 files changed, 75 insertions, 47 deletions

diff --git a/Bugzilla/Extension.pm b/Bugzilla/Extension.pm
index 17193f1b6..e24ceb9eb 100644
--- a/Bugzilla/Extension.pm
+++ b/Bugzilla/Extension.pm
@@ -651,6 +651,21 @@ So, for example, if you had a CSS file called F<style.css> and your
 extension was called F<Foo>, your file would go into 
 F<extensions/Foo/web/style.css>.
 
+=head2 Documenting Extensions
+
+Documentation goes in F<extensions/Foo/docs/en/rst/>, if it's in English, or
+change "en" to something else if it's not. The user documentation index file
+must be called index-user.rst; the admin documentation must be called
+index-admin.rst. These will end up in the User Guide and the Administration
+Guide respectively. Both documentation types are optional. You can use various
+Sphinx constructs such as :toctree: or :include: to include further reST files
+if you need more than one page of docs.
+
+When documenting extensions to the Bugzilla API, if your extension provides
+them, the index file would be F<extensions/Foo/docs/en/rst/api/v1/index.rst>.
+When and if your API has more than one version, increment the version number.
+These docs will get included in the WebService API Reference.
+
 =head2 Disabling Your Extension
 
 If you want your extension to be totally ignored by Bugzilla (it will
diff --git a/docs/en/rst/administering/extensions.rst b/docs/en/rst/administering/extensions.rst
index 0d5a216af..2c54b8463 100644
--- a/docs/en/rst/administering/extensions.rst
+++ b/docs/en/rst/administering/extensions.rst
@@ -1,4 +1,4 @@
-.. _installed-extensions:
+.. _installed-extensions-admin:
 
 Installed Extensions
 ====================
@@ -15,4 +15,4 @@ last time you compiled the documentation):
    :maxdepth: 1
    :glob:
    
-   ../extensions/*
+   ../extensions/*/index-admin
diff --git a/docs/en/rst/api/index.rst b/docs/en/rst/api/index.rst
index 55c997a68..45055eba1 100644
--- a/docs/en/rst/api/index.rst
+++ b/docs/en/rst/api/index.rst
@@ -9,5 +9,5 @@ This Bugzilla installation has the following WebService APIs available
 .. toctree::
    :glob:
 
-   core/v*/index*
-   extensions/*/v*/index*
+   core/v*/index
+   ../extensions/*/api/v*/index
diff --git a/docs/en/rst/using/extensions.rst b/docs/en/rst/using/extensions.rst
new file mode 100644
index 000000000..752b50b9a
--- /dev/null
+++ b/docs/en/rst/using/extensions.rst
@@ -0,0 +1,18 @@
+.. _installed-extensions-user:
+
+Installed Extensions
+====================
+
+Bugzilla can be enhanced using extensions (see :ref:`extensions`). If an
+extension comes with documentation in the appropriate format, and you build
+your own copy of the Bugzilla documentation using :file:`makedocs.pl`, then
+the documentation for your installed extensions will show up here.
+
+Your Bugzilla installation has the following extensions available (as of the
+last time you compiled the documentation):
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+   
+   ../extensions/*/index-user
diff --git a/docs/en/rst/using/index.rst b/docs/en/rst/using/index.rst
index f336b3729..73aa707c3 100644
--- a/docs/en/rst/using/index.rst
+++ b/docs/en/rst/using/index.rst
@@ -15,4 +15,5 @@ User Guide
    reports-and-charts
    tips
    preferences
+   extensions
 
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index 811ef8bc5..31ad0c610 100755
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -12,11 +12,13 @@
 #
 # 1) Sphinx documentation builder (python-sphinx package on Debian/Ubuntu)
 #
-# 2) pdflatex, which means the following Debian/Ubuntu packages:
-#    * texlive-latex-base
-#    * texlive-latex-recommended
-#    * texlive-latex-extra
-#    * texlive-fonts-recommended
+# 2a) rst2pdf
+# or
+# 2b) pdflatex, which means the following Debian/Ubuntu packages:
+#     * texlive-latex-base
+#     * texlive-latex-recommended
+#     * texlive-latex-extra
+#     * texlive-fonts-recommended
 #
 # All these TeX packages together are close to a gig :-| But after you've
 # installed them, you can remove texlive-latex-extra-doc to save 400MB.
@@ -143,25 +145,15 @@ foreach my $lang (@langs) {
 
     # Collect up local extension documentation into the extensions/ dir.
     # Clear out old extensions docs
-    rmtree('rst/extensions', 0, 1);
-    mkdir('rst/extensions');
-    rmtree('rst/api/extensions', 0, 1);
-    mkdir('rst/api/extensions');
+    # For the life of me, I cannot get rmtree() to work here. It just returns
+    # silently without deleting anything - no errors.
+    system("rm -rf $lang/rst/extensions/*");
 
     foreach my $ext_name (keys %extensions) {
-        foreach my $path (glob($extensions{$ext_name} . "/*")) {
-            my ($file, $dir) = fileparse($path);
-            if ($file eq 'api') {
-                my $dst = "$docparent/$lang/rst/api/extensions/$ext_name";
-                mkdir($dst) unless -d $dst;
-                rcopy("$path/*", $dst);
-            }
-            else {
-                my $dst = "$docparent/$lang/rst/extensions/$ext_name";
-                mkdir($dst) unless -d $dst;
-                rcopy($path, "$dst/$file");
-            }
-        }
+        my $src = $extensions{$ext_name} . "/*";
+        my $dst = "$docparent/$lang/rst/extensions/$ext_name";
+        mkdir($dst) unless -d $dst;
+        rcopy($src, $dst);
     }
 
     chdir "$docparent/$lang";
diff --git a/extensions/Example/docs/en/rst/example.rst b/extensions/Example/docs/en/rst/example.rst
deleted file mode 100644
index f2c055bae..000000000
--- a/extensions/Example/docs/en/rst/example.rst
+++ /dev/null
@@ -1,21 +0,0 @@
-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/Example/docs/en/rst/index-admin.rst b/extensions/Example/docs/en/rst/index-admin.rst
new file mode 100644
index 000000000..220319f99
--- /dev/null
+++ b/extensions/Example/docs/en/rst/index-admin.rst
@@ -0,0 +1,12 @@
+Example
+#######
+
+This is a sample Adminstration 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 Administration Guide. If you need more than one file's
+worth of admin documentation, include others using the Sphinx `toctree
+directive <http://sphinx-doc.org/markup/toctree.html>`_.
diff --git a/extensions/Example/docs/en/rst/index-user.rst b/extensions/Example/docs/en/rst/index-user.rst
new file mode 100644
index 000000000..192075d10
--- /dev/null
+++ b/extensions/Example/docs/en/rst/index-user.rst
@@ -0,0 +1,11 @@
+Example
+#######
+
+This is a sample User 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 User Guide. If you need more than one file's worth of
+user documentation, include others using the Sphinx `toctree directive <http://sphinx-doc.org/markup/toctree.html>`_.