[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: About the generate_html package

From: Julien Bect
Subject: Re: About the generate_html package
Date: Mon, 18 Aug 2014 19:17:11 +0200
User-agent: Mozilla/5.0 (X11; Linux i686; rv:31.0) Gecko/20100101 Thunderbird/31.0

Le 17/08/2014 22:03, Carnë Draug a écrit :
On 15 August 2014 19:03, Julien Bect <address@hidden> wrote:
By the way, the current generate_html package is from october 2012 and
several changes have been made to it recently (including the new "NEWS" and
"Package Documentation" links, which can already be seen in the doc of the
optim package). Perhaps now would be a good time for a 0.2 ? Please tell me
if there's anything I can do to help.
I have just made a 0.1.6 release. I'd reserve a 0.2 release if there's
an actual change on the structure of the site.

Well, new links have been added, that's why I was suggesting 0.2 instead of 0.1.6. Nevermind.

You mentioned a series of problems on the current website which I
agree do exist and would welcome fixes for it. Both generate_html and
the website now have hg repos. The main problem would be that big
changes would require rebuild of all packages documentation. Since
most of the changes would be text that is equal on all pages, we could
work around this by editing the file in places with some per script.

Here is my opinion on this:

1) Since the HTML documentation cannot easily be regenerated by the OF website maintainer (it requires the installation of the package, not always easy, + sometimes various customizations performed by the packages maintainer), it must be considered as part of the source code of the website.

2) Assuming no heavy customization of the html generated by generate_package_html, it is easy to extract separate the actual content of all the existing pages from the header+footer decoration. Actually, I already have a script to do it (looking for <div id="doccontent"> </div>) and I have done it locally for the 94 packages that are currently documented online (61 maintained + 33 unmaintained). Only a few problems (<div> without a matching </div>) that I can report later if you like.

3) Considering 1) and 2) I would suggest a) archiving the "doccontent" part of all the existing documentation on the project-web repository, b) extracting the content of the static pages in a similar fashion, and then c) writing a script that recreates the website (entirely, or for one package only) based on this + the header and the footer.

In this way of doing things, the process for releasing a package would be slightly modified (but not more complicated, hopefully). When the package maintainer sends its HTML documentation, the OF maintainer would simply (I hope) have to run a script that does the following : a) separate the content (to be saved) from the header and footer (to be discarded); b) replace the old content by the new content on mercurial ("hg addremove" should be useful for that) and c) generate the full HTML pages from the current header and footer (the package maintainer might have used an older version) ready to be uploaded.

A necessary condition for this to work is that package maintainer refrain from doing any customization of the HTML generated by generate_package_html outside the <div id="doccontent"> </div> pair.

What do you think ? Does it seem like a reasonable plan to you, or am I again missing something ?


reply via email to

[Prev in Thread] Current Thread [Next in Thread]