963120 - Allow extensions to document themselves, and build result into docs

Status: RESOLVED FIXED

(Bugzilla :: Documentation, enhancement)

Description

[Gervase Markham [:gerv]]

We should have a mechanism whereby extensions can put a .rst file in their top-level directory which explains the extension, and we find those and build them into an "Extensions" chapter at the end of the documentation.

Gerv

Comment 1

[Frédéric Buclin]

Let's first see if someone works on this before targetting the bug.

Comment 2

[Gervase Markham [:gerv]]

Attachment: Patch v.0.1

Here's one way to do it. Asking for review because it seems the Bugzilla product doesn't have the "feedback?" flag for attachments. I'm looking for feedback on my general approach here.

I think it's probably hard to get Sphinx to look for .rst documents outside the tree which has conf.py at the top, so I elected to use makedocs.pl to copy them in to docs/en/rst/extensions/ instead. Each extension can have one .rst file, and it will be included as a subsection in a new "Extensions" top-level section. 

I suspect I will need to replace the "find" command with a cross-platform solution, if we want it to build on Windows. 

Gerv

Comment 3

[Frédéric Buclin]

Comment on attachment 8365309 [details] [diff] [review]
Patch v.0.1

>=== modified file 'docs/en/rst/index.rst'

>    customization
>    troubleshooting
>+   extensions
>    patches

I think the order should be changed to extensions - customization - patches - troubleshooting.



>=== modified file 'docs/makedocs.pl'

>+    system("find ../../extensions -name '*.rst' -exec cp {} rst/extensions \\;");

You should use File::Find and File::Copy instead of system(). Both modules are in the core distribution of Perl.


>=== added file 'extensions/Voting/voting.rst'

Documentation should go into extensions/Voting/doc/voting.rst. This would let an extension author add more documentation without polluting the root directory.


>+Here are some sample extension docs, for the voting extension.

Please write real documentation, or do it for the Example extension only. In all cases need the Example extension such a file.

Comment 4

[Frédéric Buclin]

(In reply to Frédéric Buclin from comment #3)
> Documentation should go into extensions/Voting/doc/voting.rst.

And voting.rst should probably be renamed to something more standard, like help.rst or documentation.rst or tutorial.rst or something similar.

Comment 5

[Gervase Markham [:gerv]]

(In reply to Frédéric Buclin from comment #4)
> And voting.rst should probably be renamed to something more standard, like
> help.rst or documentation.rst or tutorial.rst or something similar.

If all the tutorial docs are all going to be copied into the extensions/ directory, then they all need to have different names. So the best rule is to have the doc named after the extension. I think it's OK to require that each extension only use a single .rst file. This means we can avoid issues with name clashes. And it means we don't need a doc/ subdir for a single file.

Gerv

Comment 6

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #5)
> If all the tutorial docs are all going to be copied into the extensions/
> directory, then they all need to have different names.

In that case, you shouldn't blindly copy everything with the .rst extension. You should enforce to use the exact same name as the extension itself.


> I think it's OK to require that
> each extension only use a single .rst file. This means we can avoid issues
> with name clashes. And it means we don't need a doc/ subdir for a single
> file.

As an extension author, I could write additional documentation, such as .txt, .pdf or .html, etc... It's a good practice to not put all the documentation in root directory. Once extension authors see the doc/ directory, they will start putting their doc there.

You should also fix extensions/create.pl to create such a default doc/$ext_name.rst file.

Comment 7

[Gervase Markham [:gerv]]

Using makedocs.pl to assemble the docs means that the docs on bugzilla.readthedocs.org won't have documentation for any extensions, including those shipped with Bugzilla. Is this acceptable?

If not, we could perhaps do something with symlinks, having symlinks there by default for the shipped extensions, and having makedocs.pl add new symlinks if it finds new extensions. Not sure if this would work on Windows, though.

LpSolit/mcote: what do you think?

Gerv

Comment 8

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #7)
> If not, we could perhaps do something with symlinks, having symlinks there
> by default for the shipped extensions, and having makedocs.pl add new
> symlinks if it finds new extensions. Not sure if this would work on Windows,
> though.
> 
> LpSolit/mcote: what do you think?

I'm not sure it will work on Windows either. So if I understand correctly, RTD doesn't run makedocs.pl itself, it runs Makefile directly? About extensions, it's fine to omit them from RTD. Extensions are disabled by default, and so probably most installations do not use them.

Comment 9

[Gervase Markham [:gerv]]

RTD doesn't run makedocs.pl, and it doesn't run the Makefile. It runs Sphinx directly.

If we are OK to omit extensions from RTD, then I will proceed on the basis of the patch as now designed.

Gerv

Comment 10

[Gervase Markham [:gerv]]

Attachment: Patch v.1

How about this?

Gerv

Comment 11

[Frédéric Buclin]

Comment on attachment 8372400 [details] [diff] [review]
Patch v.1

On checkin, make sure to also fix t/008filter.t to ignore .rst files, see line 83:

    if ($file =~ /\.(pm|txt|rst|png)\.tmpl$/) {


r=LpSolit with this fix.

Comment 12

[Gervase Markham [:gerv]]

LpSolit: Are you sure we need that? There are no ".rst.tmpl" files, at least not now... 

Gerv

Comment 13

[Frédéric Buclin]

(In reply to Gervase Markham [:gerv] from comment #12)
> LpSolit: Are you sure we need that? There are no ".rst.tmpl" files

Yes, I'm sure. We now have template/en/default/extensions/name.rst.tmpl.

Comment 14

[Dave Miller [:justdave]]

Don't forget comment 11.

Comment 15

[Gervase Markham [:gerv]]

Committing  to: bzr+ssh://bzr.mozilla.org/bugzilla/trunk/
                                                         
added template/en/default/extensions/name.rst.tmpl
modified docs/en/rst/index.rst
modified docs/makedocs.pl
modified t/008filter.t
modified extensions/create.pl
added extensions/Example/doc/example.rst
added docs/en/rst/extensions.rst
added extensions/Example/doc
Committed revision 8926.   

Gerv