Bugzilla should ship with built perldoc

RESOLVED FIXED in Bugzilla 3.0

Status

()

Bugzilla
Documentation
--
enhancement
RESOLVED FIXED
12 years ago
11 years ago

People

(Reporter: Max Kanat-Alexander, Assigned: Max Kanat-Alexander)

Tracking

(Blocks: 1 bug)

2.23
Bugzilla 3.0
Bug Flags:
approval +

Details

Attachments

(1 attachment, 4 obsolete attachments)

(Assignee)

Description

12 years ago
I'd like to see all of the API docs ship with Bugzilla in HTML format. This is going to be particularly important now that we have an XML-RPC interface, because we have API docs that people will actually really need to read.

Basically, all of the .pm files should be built in text and HTML formats for the api docs, and for the HTML docs it should be linked from the Guide if possible. And then any .pl files that have perldoc should also be included.

If possible I'd like the perldoc.perl.org style, or the CPAN style, for our pod2html.

Comment 1

12 years ago
(In reply to comment #0)
> If possible I'd like the perldoc.perl.org style, or the CPAN style, for our
> pod2html.

Are we able to ship those styles with Bugzilla? 

(Assignee)

Comment 2

12 years ago
(In reply to comment #1)
> Are we able to ship those styles with Bugzilla? 

  I think so. Even if we aren't, the CSS itself is available publicly on the Internet, and we can link to it. I just have to figure out how to get the styles to look exactly right.

Comment 3

12 years ago
(In reply to comment #2)
>   I think so. Even if we aren't, the CSS itself is available publicly on the
> Internet, and we can link to it. 

Ugh - I don't like that idea. Don't like things that do cross-domain linking, normally. I'd rather we just wrote our own CSS instead of starting to make the docs depend on another website being up (particularly if they are on bz.org.
(Assignee)

Comment 4

12 years ago
  Okay. Well, we can work it out. As long as it looks nice.

  Here's what I have so far. This code, if put in a script in the docs/ directory and run from the docs/ directory, will build all our POD:

use Pod::Simple::HTMLBatch;
my $converter = Pod::Simple::HTMLBatch->new;
$converter->add_css('http://perldoc.perl.org/css.css');
$converter->batch_convert(['../'], 'api/');
(Assignee)

Comment 5

12 years ago
We could also maybe use Template::Plugin::PodSimple: 

http://search.cpan.org/~podmaster/Template-Plugin-PodSimple-1.010/lib/Template/Plugin/PodSimple.pm
(Assignee)

Comment 6

12 years ago
Okay, so I had to put the code into a separate file, for code reasons. Basically, it uses Pod::Simple::HTMLBatch, and I don't want makedocs.pl to fail if that module isn't installed. So if people want to build the POD, they'll have to run a separate script. That's not so bad, though. This way we won't break makedocs.pl for people who don't currently have Pod::Simple installed.
Assignee: documentation → mkanat
Summary: makedocs.pl should also build perldoc → Bugzilla should ship with built perldoc
(Assignee)

Comment 7

12 years ago
Created attachment 235974 [details] [diff] [review]
v1

Okay, here we go! This makes the POD and makes it look nice.

You can see a sample at:

http://landfill.bugzilla.org/mkanat/docs/api/

I also fixed a tiny bug in Bugzilla::Install::Filesystem. You can trust my changes there as module owner, you don't have to review them.
Attachment #235974 - Flags: review?(colin.ogilvie)
(Assignee)

Comment 8

12 years ago
Created attachment 235996 [details] [diff] [review]
v2

This version contains a few improvements.
Attachment #235974 - Attachment is obsolete: true
Attachment #235996 - Flags: review?
Attachment #235974 - Flags: review?(colin.ogilvie)
(Assignee)

Updated

12 years ago
Attachment #235996 - Flags: review? → review?(colin.ogilvie)

Comment 9

12 years ago
Comment on attachment 235996 [details] [diff] [review]
v2

Comments (not reviewing the patch just yet as I'm at work):

1) The font sizes seem large compared to normal sizes for the text use.
2) The format of the 'index' page could be better - perhaps in a more heirarchical structure?

  Bugzilla.pm
    Bugzilla/Install.pm
      Bugzilla/Install/Localconfig.pm

Comment 10

12 years ago
(In reply to comment #6)
> Okay, so I had to put the code into a separate file, for code reasons.
> Basically, it uses Pod::Simple::HTMLBatch, and I don't want makedocs.pl to fail
> if that module isn't installed.

Why not wrap it in an "eval" call so that it's all in the one script?
(Assignee)

Comment 11

12 years ago
(In reply to comment #9)
> 1) The font sizes seem large compared to normal sizes for the text use.

  Yeah...are you reviewing it on Windows or on Linux? It's just the standard size that your browser renders for a sans-serif font. I'd like to make it a wee bit smaller though, also. I just have to make sure the <code> sections and all that aren't affected.

> 2) The format of the 'index' page could be better - perhaps in a more
> heirarchical structure?

  I'd love that. Unfortunately, that's a HUGE amount of work. What you see is generated by a gigantic code tangle in Pod::Simple::HTMLBatch. We should file another bug to make a better index page.
(Assignee)

Comment 12

12 years ago
(In reply to comment #10)
> Why not wrap it in an "eval" call so that it's all in the one script?

  I could. I'd also have to do that for the Pod::Simple stuff in the package, and there's a BEGIN block there that has to run at compile time, not at run-time, and so on...at the worst, I could put the package into a separate file, but I'd have no idea where to put it. It makes sense for the package to be defined in the file.

Comment 13

12 years ago
(In reply to comment #11)
>   Yeah...are you reviewing it on Windows or on Linux? It's just the standard
> size that your browser renders for a sans-serif font. I'd like to make it a wee
> bit smaller though, also. I just have to make sure the <code> sections and all
> that aren't affected.

Was windows - and it was mainly the headers I was concerned about. 

Personally, I hate Verdana as a font at the default font-size anyway as it always looks so large.

>   I'd love that. Unfortunately, that's a HUGE amount of work. What you see is
> generated by a gigantic code tangle in Pod::Simple::HTMLBatch. We should file
> another bug to make a better index page.

Hmm, I could live with that I suppose. 

Comment 14

12 years ago
(In reply to comment #12)
>   I could. I'd also have to do that for the Pod::Simple stuff in the package,
> and there's a BEGIN block there that has to run at compile time, not at
> run-time, and so on...at the worst, I could put the package into a separate
> file, but I'd have no idea where to put it. It makes sense for the package to
> be defined in the file.

I'd suggest docs/perl/Pod/Simple/HTML/Bugzilla.pm - I (personally) hate having packages in the main file as it confuses my editor :)

Unless I'm missing something, I don't see a BEGIN block ....

Also - can I suggest you put the stylesheet in docs/ as I'd like to (in the future) have a stylesheet for the HTML documentation too... and it would make sense for them to be the same. 

I'll actually review the patch tomorrow.
(Assignee)

Updated

12 years ago
Blocks: 350643
(Assignee)

Comment 15

12 years ago
Created attachment 236152 [details] [diff] [review]
v3

Okay, here's a version with the code inside of makedocs.pl, the module in a separate file, and also the fixed CSS that we discussed on IRC.
Attachment #235996 - Attachment is obsolete: true
Attachment #236152 - Flags: review?(colin.ogilvie)
Attachment #235996 - Flags: review?(colin.ogilvie)
(Assignee)

Comment 16

12 years ago
Oh, and I forgot the license block, but if you r+ this version I'll put it there on checkin.
(Assignee)

Comment 17

12 years ago
Created attachment 236167 [details] [diff] [review]
v4

Okay, here's one that makes a better index page, like you wanted. :-)
Attachment #236152 - Attachment is obsolete: true
Attachment #236167 - Flags: review?(colin.ogilvie)
Attachment #236152 - Flags: review?(colin.ogilvie)

Comment 18

12 years ago
Comment on attachment 236167 [details] [diff] [review]
v4

r- due to the following:

1) Script appears to fail initially, as there's no html/api directory created by either this script or checksetup.pl
2) CSS does not appear to end up in the correct place

>Index: Bugzilla/Install/Filesystem.pm

mkanat is the owner of this, trusting his judgement ;)

>Index: docs/makedocs.pl

>+sub make_pod {
>+
>+    print "Creating API documentation...\n";
>+
>+    my $converter = Pod::Simple::HTMLBatch::Bugzilla->new;
>+    # This class is defined below, in this file.

Nit: No it's not :)

Nit: It would be nicer if this didn't spew quite so much debugging information, but not sure how much control we have over it.

Some of our POD links to files that don't generate anything ATM, resulting in 404s. Constants.pm is the one I noticed was missing. If there's not a bug for adding it, please do so (or remove the reference that generates it).
Attachment #236167 - Flags: review?(colin.ogilvie) → review-
(Assignee)

Updated

12 years ago
Status: NEW → ASSIGNED
(Assignee)

Comment 19

12 years ago
Created attachment 236549 [details] [diff] [review]
v5

Ah, you were right! I fixed everything, including all the .cvsignore files.
Attachment #236167 - Attachment is obsolete: true
Attachment #236549 - Flags: review?(colin.ogilvie)

Comment 20

12 years ago
Comment on attachment 236549 [details] [diff] [review]
v5

Looks good to me, although you will need approval to check in due to the code changes...
Attachment #236549 - Flags: review?(colin.ogilvie) → review+

Comment 21

12 years ago
Note this will require changes to the bugzilla.org website (although it is broken just now anyway wrt. the docs)
(Assignee)

Updated

12 years ago
Flags: approval?
(Assignee)

Updated

12 years ago
Keywords: relnote
Flags: approval? → approval+
(Assignee)

Comment 22

12 years ago
Checking in Bugzilla/Install/Filesystem.pm;
/cvsroot/mozilla/webtools/bugzilla/Bugzilla/Install/Filesystem.pm,v  <--  Filesystem.pm
new revision: 1.11; previous revision: 1.10
done
Checking in docs/.cvsignore;
/cvsroot/mozilla/webtools/bugzilla/docs/.cvsignore,v  <--  .cvsignore
new revision: 1.3; previous revision: 1.2
done
Checking in docs/makedocs.pl;
/cvsroot/mozilla/webtools/bugzilla/docs/makedocs.pl,v  <--  makedocs.pl
new revision: 1.13; previous revision: 1.12
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/html/.cvsignore,v
done
Checking in docs/html/.cvsignore;
/cvsroot/mozilla/webtools/bugzilla/docs/html/.cvsignore,v  <--  .cvsignore
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/html/api/.cvsignore,v
done
Checking in docs/html/api/.cvsignore;
/cvsroot/mozilla/webtools/bugzilla/docs/html/api/.cvsignore,v  <--  .cvsignore
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/html/api/style.css,v
done
Checking in docs/html/api/style.css;
/cvsroot/mozilla/webtools/bugzilla/docs/html/api/style.css,v  <--  style.css
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/lib/Pod/Simple/HTML/Bugzilla.pm,v
done
Checking in docs/lib/Pod/Simple/HTML/Bugzilla.pm;
/cvsroot/mozilla/webtools/bugzilla/docs/lib/Pod/Simple/HTML/Bugzilla.pm,v  <-- Bugzilla.pm
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm,v
done
Checking in docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm;
/cvsroot/mozilla/webtools/bugzilla/docs/lib/Pod/Simple/HTMLBatch/Bugzilla.pm,v <--  Bugzilla.pm
initial revision: 1.1
done
RCS file: /cvsroot/mozilla/webtools/bugzilla/docs/xml/.cvsignore,v
done
Checking in docs/xml/.cvsignore;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/.cvsignore,v  <--  .cvsignore
initial revision: 1.1
done
Status: ASSIGNED → RESOLVED
Last Resolved: 12 years ago
Resolution: --- → FIXED
(Assignee)

Comment 23

11 years ago
Added to the release notes on bug 255155.
Keywords: relnote
(Assignee)

Comment 24

11 years ago
The correct bug number for those release notes is actually bug 349423.
You need to log in before you can comment on or make changes to this bug.