From 34477d3793d308de20711a4df48f7823c91baaba Mon Sep 17 00:00:00 2001 From: Gervase Markham Date: Tue, 25 Feb 2014 12:00:48 +0000 Subject: Bug 963120 - allow extensions to document themselves, and build result into docs. r=LpSolit, a=justdave. --- docs/en/rst/extensions.rst | 11 +++++++++++ docs/en/rst/index.rst | 3 ++- docs/makedocs.pl | 20 ++++++++++++++++++++ extensions/Example/doc/example.rst | 22 ++++++++++++++++++++++ extensions/create.pl | 3 ++- t/008filter.t | 2 +- template/en/default/extensions/name.rst.tmpl | 23 +++++++++++++++++++++++ 7 files changed, 81 insertions(+), 3 deletions(-) create mode 100644 docs/en/rst/extensions.rst create mode 100644 extensions/Example/doc/example.rst create mode 100644 template/en/default/extensions/name.rst.tmpl 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 `_ +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/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 `_ +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. -- cgit v1.2.3-24-g4f1b