Commit 4e15a133 authored by Gervase Markham's avatar Gervase Markham

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

parent 40a522aa
......@@ -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
......
.. _installed-extensions:
.. _installed-extensions-admin:
Installed Extensions
====================
......@@ -15,4 +15,4 @@ last time you compiled the documentation):
:maxdepth: 1
:glob:
../extensions/*
../extensions/*/index-admin
......@@ -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
.. _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
......@@ -15,4 +15,5 @@ User Guide
reports-and-charts
tips
preferences
extensions
......@@ -12,7 +12,9 @@
#
# 1) Sphinx documentation builder (python-sphinx package on Debian/Ubuntu)
#
# 2) pdflatex, which means the following Debian/Ubuntu packages:
# 2a) rst2pdf
# or
# 2b) pdflatex, which means the following Debian/Ubuntu packages:
# * texlive-latex-base
# * texlive-latex-recommended
# * texlive-latex-extra
......@@ -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 $src = $extensions{$ext_name} . "/*";
my $dst = "$docparent/$lang/rst/extensions/$ext_name";
mkdir($dst) unless -d $dst;
rcopy($path, "$dst/$file");
}
}
rcopy($src, $dst);
}
chdir "$docparent/$lang";
......
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`.
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>`_.
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>`_.
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment