[sane-devel] SANE website on GitLab Pages (was Re: GitLab mirrors, GitLab-CI builds and GitLab Pages)

Tue Jun 21 13:23:50 UTC 2016

Hi allan,

First, a bit of background is probably in order.  I am playing around on
GitLab trying to automate parts of the SANE development process.  Some
of this is done already at Alioth but I get the impression that Alioth
is not good enough or at least behind the curve.

Below are my findings with respect to the website repository and the
project's home pages at http://www.sane-project.org/

I am mostly looking for advice/feedback on how to proceed and improve.
With that in the back of your head, please read on.

Olaf Meeuwissen writes:

> [... based on the GitLab mirror of the website repository ...]
> The website is rebuilt with every sync/commit as well and, if the build
> was successfull and passed the tests, "deployed" to
>
>   https://sane-project.gitlab.io/
>
> Right now, there is very little testing going on (and even if there is a
> problem the tests succeed).  Also, not all of the current website is up
> yet.  Consider this a work in progress.

I've been poking around a bit on alioth.debian.org, specifically in
/home/groups/sane/bin/ in an attempt to reduce the error count on the
GitLab Pages.  At the moment, these pages aims to mirror what's on
www.sane-project.org but I'd like to give that a bit of an update (and
face lift).

Anyway, of the scripts in that directory make-git-snapshots.sh and
update-htdocs.sh appear to run daily.  The update-lists.sh and
update-search.sh scripts seem to run approximately weekly.  All this
appears to be coordinated by kitno-guest cron jobs on alioth.

I've got the make-git-snapshots and update-lists parts covered in my CI
builds just fine (apart from the daily trigger but that can be solved,
see https://gitlab.com/help/ci/triggers/README.md which actually makes
me believe that commits to sane-backends can be used to trigger updates
for the website, cool!).

# Just noticed that the snapshots/ index doesn't render.  That's due to
# the GitLab Pages being static and not backed by a web server HTMLizing
# directory listings :-(  Todays tarballs *are* there, though.

I even have the update-sanei-docs part covered.  The official website is
using something that was generated 2011-01-31 by the looks of it.  Guess
the lack of doxygen on alioth is to blame for that.  Is that right?

With the above I think I have most of update-htdocs covered.  The only
thing that seems to be missing is the relink to the old-archive.  That
is a static directory and I am pondering how to get this integrated
without undue overhead with every rebuild of the GitLab Pages site.

The CGI interfaces to search the old-archive and supported device lists
(input files maintained by update-search.sh?)  are something that won't
work on a static site as exposed by the GitLab Pages.  The device lists
might still work through an SPA (single page application) but the
old-archive is too big to handle that way.  Do we still need it?

The unused-driver-cvs.sh script seems to be unused.  Is that right?

While going through getting this to work, I was wondering why the HTML'd
manual pages and SANE API specs were not updated.  Apart from the latest
released and current development version issue, I got the impression
that part of the reason is that alioth doesn't have the required tools
installed in order to automate this.  That would also explain why these
files are in the website repository.  Still, automating this would beat
the manual maintenance that is used now. 

The dlh source code[1] was last released in 1998 and isn't packaged by
any distribution that I know of.  The man2html convertor originates from
a BSD clone somewhere out there, is not compatible with Debian's
man2html and seems abandoned as of 2003[2].

 [1] ftp://ftp.cs.arizona.edu/dlh/
 [2] http://cvs.savannah.gnu.org/viewvc/man2html/man2html?root=man2html&view=log

I did get man2html to work on Debian 8 but wasn't able to get dlh to do
anything useful.  FTR, these two are used when you run

  make -C doc html-man
  make -C doc sane-html

respectively.

Seeing the current, rather sad, state of affairs, I got an urge to
replace these fossilized tools with something more up-to-date.  Any
suggestions?

# Actually, I have also been toying with the idea of converting all the
# documentation to reStructuredText.  There's plenty of tools that can
# convert that to HTML, manual pages, PDF and what not.  I have recently
# started using Sphinx[3] @the-office and that seems to support qthelp as
# well as devhelp (for GTK) and applehelp, all of which would ease the
# integration of the API documentation in application developer's IDEs
# (if I understand correctly).
#
#  [3] http://sphinx-doc.org/

> You can find the GitLab sane-project at
>
>   https://gitlab.com/groups/sane-project

Please take a look and let me (and the list?) know what you think!

Hope this helps,
-- 
Olaf Meeuwissen, LPIC-2            FSF Associate Member since 2004-01-27
 GnuPG key: F84A2DD9/B3C0 2F47 EA19 64F4 9F13  F43E B8A4 A88A F84A 2DD9
 Support Free Software                        https://my.fsf.org/donate
 Join the Free Software Foundation              https://my.fsf.org/join