Re: Status of help.gnome.org and Pintail

[Emmanuele Bassi <ebassi gmail com>]

Hi all;

I've opened a merge request for the help.gnome.org repository that adds a CI pipeline:

https://gitlab.gnome.org/Infrastructure/help.gnome.org/-/merge_requests/3

By default, it'll build the website only for the C language on all refs, and build the fully localised version only for the main development branch.

The output is then published on the GitLab pages space at the end of the pipeline.

We can ask the GNOME sysadmins to redirect help.gnome.org (or learn.gnome.org) there as soon as we have a full build.

A few things I found out while playing with this, today:

- pintail is not really blazing fast, taking 15 minutes to build the site for the default C locale; but once translations are thrown in the mix it gets **really** slow. The full build takes 3 hours on the CI runner. I haven't looked at pintail in depth, but maybe we can speed it up a bit by running each language in parallel, or cloning all repositories in parallel with a threaded executor

- there are a bunch of gotchas in the configuration; it really needs more documentation

- the design team should have a go at the CSS and general styling; each card should have the same size, for instance

- we really need to go through the user documentation and vet what should be kept and what should be improved/dropped

- the list of applications should probably be matching apps.gnome.org

- we need a way to link to the help page from the apps metainfo, so we can easily go from apps.gnome.org to help|learn.gnome.org

Ciao,

 Emmanuele.

On Wed, 26 May 2021 at 15:45, Shaun McCance <shaunm gnome org> wrote:

Folks,

I've been off-and-on working on retooling help.gnome.org using Pintail,
the documentation publishing platform built for Mallard and Ducktype.
I'd like to get this finally finished. I could use help.

Here is a current preview:

https://people.gnome.org/~shaunm/help.gnome.org/

Here is the repo that builds it:

https://gitlab.gnome.org/Infrastructure/help.gnome.org/

The README is up to date, I believe.

Pintail builds from git, not tarballs. A full site rebuild without
translations takes about 6 minutes for me, which includes the time it
takes to git pull. With translations, it takes about 3 hours. If run in
containers without persistent storage for checkouts, it could take much
longer for all those git clones. It's possible to do partial rebuilds,
but there are things to be aware of that I won't get into in this
email.

Things remaining to do:

* I hacked together the style. I think it looks ok. People who live web
design can probably do better.

* There's no site search right now, but this is something Pintail is
designed to support (and support really well). The existing search
plugin uses Elasticsearch, which is problematic. We need a new plugin
based on OpenSearch, Apache Solr, or something else. I mostly know how
to do this, but I'm having a hard time finding the bandwidth. We can
launch without this, but I'd be sad.

* Petr, David, and I had a long conversation about publishing old
versions and decided against it. You have those locally installed. We
can revisit this if people want.

* Speaking of which, the URL format is vastly simplified. Instead of
/users/gnome-help/stable/, it's just /gnome-help/ for the core GNOME
help. This means we need to set up a .htaccess with redirects. I'd very
much like to have this as a Pintail feature, if someone wants to do
some Python. But we can also just hand-write a .htaccess file.

* We did decide on publishing an unstable preview for select documents.
These all live under /unstable/. We need a robots.txt so that El Google
never ever ever lands people there. I'd very much like to have this as
a Pintail feature, if someone wants to do some Python. But we can also
just hand-write a robots.txt file.

* We have to actually deploy it somewhere other than my personal space
on people.gnome.org. This will take involvement from our admins, of
course, but also on our part to see things thru.

* (Preview of what I'm going to talk about in my GUADEC presentation:
I'd like to rename the site to learn.gnome.org and start to shift our
focus toward learning-based material.)

--
Shaun


_______________________________________________
gnome-doc-list mailing list
gnome-doc-list gnome org
https://mail.gnome.org/mailman/listinfo/gnome-doc-list

--

https://www.bassi.io
[@] ebassi [@gmail.com]