Enabling TAGS_SAVE_AS causes site build to fail

[bdelacretaz]

I'm trying to enable the Pelican tag-based navigation for www.apache.org
(apache/www-site#196) and as a first step I tried enabling the TAGS_SAVE_AS feature, by hardcoding it for now, setting TAGS_SAVE_AS = 'tags.html' in bin/pelican.auto.ezt

Just doing this causes a site build of the sibling template-site repository to fail with

WARNING  Caught exception: log.py:91 'page' is undefined".

It looks like something in this module is getting in the way, but I know little about Pelican and even less about Python so I'm not sure where to look. Pointers are welcome.

Here's my failure scenario:

$ cd infrastructure-pelican
$ git diff bin/pelican.auto.ezt  
 ...
-TAGS_SAVE_AS = ''
+TAGS_SAVE_AS = 'tags.html'
...

$ docker build -t pelican-asf2 .

# try to build https://github.com/apache/template-site
$ cd ../template-site
$ rm -rf site-generated && docker run -it -p12345:8000 -v $PWD:/site pelican-asf2
...
WARNING  Caught exception:
    page' is undefined".

And the site-generated folder is not created, nothing is generated.

[sebbASF]

AFAICT the same applies to all the other settings in the same section: not only are the features currently unused, they are unsupported at present

[sebbASF]

It looks like the page reference is coming from the template, specifically base.html. But I have no idea how to fix the issue.

[sebbASF]

I had a sudden idea: Pelican uses templates for tags (and authors etc).
These extra templates are currently missing from the ASF theme; I think that means Pelican reverts to using base.html.
The 'page' variable is presumably only set up for pages, not tags.

I've checked the Pelican simple template example, and it does not reference 'page' in the base.html template file.
The ASF template probably ought to do the same - i.e. page references should be moved to page.html.

As a temporary work-round, I think it would be possible to derive tag.html and tags.html from a different base.
Certainly the page error disappears in the website-template build when empty tag(s).html files are present.

[sebbASF]

I think this needs to be fixed by changes to the template(s).
However, there does not currently seem to be any way to enable tags except by changing the pelican.auto.ezt template.
This will likely break lots of builds, as it may require template changes.
There needs to be a way to change the tags setting for each site, e.g. in pelicanconf.yaml

[bdelacretaz]

Another option might be to fork the templates for the www-site project and work there to enable tags. I don't know how much interest there is in tags from other ASF sites using the infrastructure-pelican templates, but I think having tags for www-site would be very helpful. Maybe www-site deserves to be treated as a special case, as it has a lot of historic content and continues to be managed by a mostly loosely-coupled team.

However, as mentioned, I'm not a Pelican or Python expert by far, so I'm not sure of the consequences of such a fork.

[sebbASF]

Two changes are needed to enable tags:

1. setting TAGS_SAVE_AS to something other than an empty string
2. fixing the templates so tag generation doesn't reference the undefined 'page' variable.

However if TAGS_SAVE_AS is unconditionally updated in this repo, then (as has been seen) all Pelican builds that use the ASF template will fail.

AFAICT the www-site uses its own copy of the templates, so a fork is not needed.

So the www-site templates can be fixed without affecting other builds, but there needs to be a way to change the TAGS_SAVE_AS setting on a per site basis.

This is nothing to do with Pelican or Python per se.

[sebbASF]

Note that tags are only processed by Pelican in articles, not in pages.
This appears to be tricky to change.

See apache/www-site#196 (comment) for a possible solution