Move to web-based documentation?

[GeraldJansen]

In view of the current situation w.r.t. packaging and installation (see #399), I would like to propose moving the documentation pages towards a web-based solution like readthedocs.org. The application's current Help menu item would be replaced by an About dialog with a link to the URL of the web documentation. This would reduce the complexity of manual installation because normal users would not have to build and install the documentation at all and thus would not need dependencies such as gnome-doc-utils xlstproc docbook-utils yelp. I would be willing to work on this if there is agreement about the direction.

[GeraldJansen]

For a proof of concept, see https://geraldjansen.github.io/hamster-doc/ which is based on the markdown files here https://github.com/GeraldJansen/hamster-doc/tree/master.

[ederag]

On the one hand your arguments are totally valid,
and the proof of concept looks nice at first sight.
On the other hand, mallard/yelp docs look nice and reactive,
and I'm reluctant to throw away so much work done by our predecessors,
in particular the translations.

[GeraldJansen]

If we decide to proceed I will try to retain the translations. The translated pages would be viewable at https://???.github.io/hamster/xx/index.html (xx in fr, de etc.) and the link in the About dialog would point to the appropriate language specific page.

It would also be possible to store previously released versions in version-specific subdirectories, eg. .../hamster/v2.2/xx/*.

[ederag]

Fine ! Is the page generation process automated ?

[GeraldJansen]

When the markdown pages are pushed/merged to the master /docs dir, the github.io pages are updated automatically. I am not yet sure how to automate the translation process, so initially I would foresee a developer running a script to generate markdown in various languages and making a pull request if there are any changes. I don't expect much action on the doc pages so it shouldn't be too much work. There should probably be an effort to update the docs before new significant releases. My time availability is also limited so no promises on timelines.

[ederag]

If a single developer has to generate web pages,
then why not use the existing infrastructure and use yelp-build ?
http://projectmallard.org/about/learn/tenminutes.html
Hold on. Got to think about it.

But I agree that the documentation build process can be separated from the installation scope, for now.

[GeraldJansen]

My motivation arose from fact that the existing infrastructure is broken as far as help pages are concerned. At least for me on XFCE, when following the instructions for manual installation with the waf scripts, the help pages do not get installed to the right location and the help window comes up with a message about a missing index page. Help also doesn't come up when running from the source directory in development mode. That made me think that, going forward, packaging and installation could be simplified by putting the documentation on static web pages instead of having to install into system documentation directories. Hence this proposal.

If you prefer to stick to the existing infrastructure, please let me know. In that case we can simply close this issue and move on.

[ederag]

I agree with you, we do need static web pages.

I had in mind an intermediate proposition:

1. keep the existing infrastructure.
   This is important, because for systems where it works (tested in gnome, KDE, LXDE),
   yelp is really good,
   and I feel like thinking twice before losing functionality.
2. generate static web pages from the existing infrastructure,
   and publish them with each release.
   This is very important for systems where the help pages are not found.

As a first step during the migration away from waf,
the static help pages will be a useful fallback,
so that we can temporarily forget the help in the installation process.
But as a next step, I would hope to bring the yelp pages back.

Then everyone should have access to help in the best way available.

I'll try to outline a more precise proposition, so that we can take a decision.

[ederag]

Here are the commands to build the whole english documentation (C) in html:

cd help
mkdir _build
cd _build

mkdir -p C/html
yelp-build html -o C/html ../C
firefox C/html/index.html

And for two pages of the french translation (as a demo)

mkdir -p fr/pages
xml2po -mmallard --po-file=../fr/fr.po ../C/index.page > fr/pages/index.page
xml2po -mmallard --po-file=../fr/fr.po ../C/input.page > fr/pages/input.page
mkdir fr/html
yelp-build html -o fr/html fr/pages
firefox fr/html/index.html

Of course it would need some automation, should we choose this route.
What do you think ?

[GeraldJansen]

Sorry for the delay in responding (due to work demands). My feeling is that we end up complicating things (including maintainance) rather than simplifying if we want to provide the docs in two ways rather than one. Also I see you are making progress with a new version of waf and that reduces my original justifications. I have no problem simply closing this issue if you agree.

[ederag]

On the one hand, it is true that having both inline (yelp) and online (static html) would be more complex.
On the other hand, online static html is good to show potential new users how hamster works,
and reduces dependencies for a "first try" installation.
In addition, I made a lot of progress with waf (struggled with gconf, almost done),
yet help pages excepted for now.
Our manpower is limited, but if someone would be kind enough to publish/maintain the html documentation,
I could automate the html build process with waf too.

[GeraldJansen]

Given your great progress on waf-update, including doc pages, my original justification for this proposal is no longer valid. Further, given the lack of manpower, I prefer to abandon this initiative.

[ederag]

OK, thank you very much for trying,
it is true that we have a lot of work to do before adding html;
I'm glad you are here !