RFC pod2rst docs changes
Jeff Fearn <[email protected]> Tue, 6 Sep 2016 17:08:40 +1000
| Newsgroups | gmane.comp.bug-tracking.bugzilla.devel |
|---|---|
| Message-ID | <[email protected]> |
This is a multi-part message in MIME format.
--------------CAAC1BB7291B7410E6E2BE4C
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
Hi, using RST bugs me and having the docs split between two UIs bugs me,
the solution, pod2rst.
Attached is a patch to replace the current pod2html with pod2rst, it's
incomplete as I'm not sure exactly where to put the rst files or how
best to integrate the docs in to the rest of the ... rest :D
Currently they get put in to docs/$lang/intergration/api/ and get added
to the bottom of the integrating docs.
https://jfearn.fedorapeople.org/bz5-docs-test/integrating/index.html
Note the poor choice of title for this section ^_^
I copied a couple of extensions in to the upstream 5.0 branch just for
demonstration.
I note that none of the extensions get added to the search, going to
have to figure that one out.
It'd be nice to put the WebServer docs in to the API docs, but should
they go in both places?
It's also be nice if we had a standard way of doing User and admin docs
in the extension pod, and putting that in the right guide.
Say Extension.pm has the user docs and lib/Config.pm has the admin docs,
or something.
What I like about that is all the information would be available both in
the POD and in the web docs, so you could always find all the docs.
Comments welcome ;)
Cheers, Jeff.
--------------CAAC1BB7291B7410E6E2BE4C
Content-Type: text/x-patch;
name="pod2rst.patch"
Content-Transfer-Encoding: quoted-printable
Content-Disposition: attachment;
filename="pod2rst.patch"
diff --git a/docs/en/rst/integrating/index.rst b/docs/en/rst/integrating/in=
dex.rst
index 816ffe8..d546290 100644
--- a/docs/en/rst/integrating/index.rst
+++ b/docs/en/rst/integrating/index.rst
@@ -20,3 +20,4 @@ explains how to use the available mechanisms for integrat=
ion and customization.
templates
extensions
apis
+ api/index
diff --git a/docs/makedocs.pl b/docs/makedocs.pl
index 36ffc45..fdb6900 100755
--- a/docs/makedocs.pl
+++ b/docs/makedocs.pl
@@ -31,6 +31,7 @@ use File::Basename;
BEGIN { chdir dirname($0); }
=20
use lib qw(.. ../lib lib);
+use open ':encoding(utf8)';
=20
use Cwd;
use File::Copy::Recursive qw(rcopy);
@@ -43,6 +44,10 @@ use Bugzilla::Constants qw(BUGZILLA_VERSION bz_locations=
);
use Pod::Simple::HTMLBatch::Bugzilla;
use Pod::Simple::HTML::Bugzilla;
=20
+use Pod::Simple::Search;
+use Pod::POM::View::Restructured;
+use File::Spec;
+
##########################################################################=
#####
# Subs
##########################################################################=
#####
@@ -57,40 +62,69 @@ sub MakeDocs {
print "\n";
}
=20
-sub make_pod {
- say "Creating API documentation...";
-
- my $converter =3D Pod::Simple::HTMLBatch::Bugzilla->new;
- # Don't output progress information.
- $converter->verbose(0);
- $converter->html_render_class('Pod::Simple::HTML::Bugzilla');
-
- my $doctype =3D Pod::Simple::HTML::Bugzilla->DOCTYPE;
- my $content_type =3D Pod::Simple::HTML::Bugzilla->META_CT;
- my $bz_version =3D BUGZILLA_VERSION;
-
- my $contents_start =3D <<END_HTML;
-$doctype
-<html>
- <head>
- $content_type
- <title>Bugzilla $bz_version API Documentation</title>
- </head>
- <body class=3D"contentspage">
- <h1>Bugzilla $bz_version API Documentation</h1>
-END_HTML
-
- $converter->contents_page_start($contents_start);
- $converter->contents_page_end("</body></html>");
- $converter->add_css('./../../../../style.css');
- $converter->javascript_flurry(0);
- $converter->css_flurry(0);
- make_path('html/integrating/api');
- $converter->batch_convert(['../../'], 'html/integrating/api');
+sub pod2rst {
+ my $path =3D shift;
+ my %callbacks =3D ();#'link' =3D> \&links,);
=20
- print "\n";
+ say "Converting POD to RST...";
+ my $name2path =3D Pod::Simple::Search->new->inc(0)->verbose(0)->survey=
(@{['../']});
+
+ my $ind_path =3D "$path/rst/integrating/api/";
+ rmtree($ind_path);
+ make_path($ind_path);
+
+ my $FILE;
+ open($FILE, '>', "$ind_path/index.rst") || die ("Can't open rst file");
+ print($FILE <<'EOI');
+.. highlight:: perl
+
+.. _developer
+
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+Developer Guide
+=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
+
+You may end hacking the code, here is the API.
+
+.. toctree::
+ :maxdepth: 2
+
+
+EOI
+
+ foreach my $mod (sort keys %$name2path) {
+ if ($mod =3D~ /^lib::/) {
+ say "Deleting %mod";
+ delete $name2path->{$mod};
+ next;
+ }
+
+ my $title =3D $mod;
+
+ $title =3D~ s/^extensions::/Bugzilla::Extension::/;
+ $title =3D~ s/lib:://;
+
+ my $abs_path =3D $name2path->{$mod};
+ my $fpath =3D File::Spec->abs2rel($abs_path, '../');
+ my ($volume,$directories,$file) =3D File::Spec->splitpath( $fpath =
);
+
+ $directories =3D~ s{^extensions/}{Bugzilla/Extension/};
+ $directories =3D~ s/lib:://;
+
+ my $dir_path =3D "$ind_path/$directories";
+ make_path($dir_path);
+ my $out_file =3D $file;
+ $out_file =3D~ s/\.[^.]*$//;
+ $out_file .=3D '.rst';
+ my $conv =3D Pod::POM::View::Restructured->new({namespace =3D> $ti=
tle});
+ my $rv =3D $conv->convert_file($abs_path, $title, "$dir_path$out_f=
ile", \%callbacks);
+ print($FILE " $directories$out_file\n");
+ }
+
+ close($FILE);
}
=20
+
##########################################################################=
#####
# Make the docs ...
##########################################################################=
#####
@@ -108,14 +142,10 @@ closedir(LANGS);
=20
my $docparent =3D getcwd();
foreach my $lang (@langs) {
- chdir "$docparent/$lang";
-
- make_pod();
+ pod2rst("$docparent/$lang");
=20
next if grep { $_ eq '--pod-only' } @ARGV;
=20
- chdir $docparent;
-
# Generate extension documentation, both normal and API
my $ext_dir =3D bz_locations()->{'extensionsdir'};
my @ext_paths =3D grep { $_ !~ /\/create\.pl$/ && ! -e "$_/disabled" }
@@ -131,6 +161,7 @@ foreach my $lang (@langs) {
# Collect up local extension documentation into the extensions/ dir.
rmtree("$lang/rst/extensions", 0, 1);
=20
+## FIXME should we pull out bits of the POD and place it in to user/admin/=
service API as appropriate?
foreach my $ext_name (keys %extensions) {
my $src =3D $extensions{$ext_name} . "/*";
my $dst =3D "$docparent/$lang/rst/extensions/$ext_name";
--------------CAAC1BB7291B7410E6E2BE4C
Content-Type: text/plain
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
MIME-Version: 1.0
-
To view or change your list settings, click here:
<https://lists.bugzilla.org/cgi-bin/mj_wwwusr?user=gcbd-developers-Uylq5CNFT+jYtjvyW6yDsg@public.gmane.org>
--------------CAAC1BB7291B7410E6E2BE4C--