From: Gervase Markham Date: Wed, 7 Jan 2015 16:01:55 +0000 (+0000) Subject: Bug 1107549 - split extension docs into User and Admin docs. r=dkl, a=glob. X-Git-Tag: release-5.1.1~399 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=70973ef7f462962c556b6c2a2dc77ff391684992;p=thirdparty%2Fbugzilla.git Bug 1107549 - split extension docs into User and Admin docs. r=dkl, a=glob. --- diff --git a/Bugzilla/Extension.pm b/Bugzilla/Extension.pm index 17193f1b67..e24ceb9eb3 100644 --- a/Bugzilla/Extension.pm +++ b/Bugzilla/Extension.pm @@ -651,6 +651,21 @@ So, for example, if you had a CSS file called F and your extension was called F, your file would go into F. +=head2 Documenting Extensions + +Documentation goes in F, 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. +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 0d5a216af0..2c54b84637 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 55c997a68c..45055eba1a 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 0000000000..28bae5be54 --- /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 f336b3729f..73aa707c31 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 811ef8bc5a..31ad0c6108 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 f2c055bae0..0000000000 --- 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 `_ -and will be compiled by `Sphinx `_. - -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 0000000000..220319f991 --- /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 `_ +and will be compiled by `Sphinx `_. + +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 `_. 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 0000000000..a6cbd8309a --- /dev/null +++ b/extensions/Example/docs/en/rst/index-user.rst @@ -0,0 +1,12 @@ +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 `_ +and will be compiled by `Sphinx `_. + +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 `_.