wiki.libvirt.org replacement

[Daniel P. Berrangé]

On Tue, Feb 14, 2023 at 11:03:20PM +0100, Peter Krempa wrote:
> https://gitlab.com/libvirt/libvirt-wiki/-/merge_requests/1
> 
> Hi,
> 
> in order to ease editing of the libvirt wiki, remove the need for
> registering users and remove the need to run PHP in an openshift instance
> I've decided to contents of the libvirt wiki into a staticaly generated
> page using (almost) the same approach we use to generate the libvirt web
> pages from rST documents in the repo.

Excellent !

> All articles were converted into rST files [1] and images linked from
> currently existing articles were dowloaded.
> 
> Advantages:
> 
>  - same workflow as with editing the libvirt pages
>  - gitlab still provides a web editor
>  - local editing for users who hate web
>  - no need to deal with user registration
>  - no need to run PHP in openshift
>  - we still keep separate space for docs which don't really belong into the
>    main repo
>  - even if we decide to kill-off the wiki eventually the valuable content
>    will be easier to port to the kbase as it'll be in rST
>  - the conversion fixed many orphaned pages

You missed the single most important benefit

 * Remove me as a single point of failure for hosting of the wiki

The wiki is attached to a personal openshift account and there's no
way for me to grant other users access to co-admin it :-( Removing
me as a failure point outweighs all the disadvantages !

> 
> Disadvantages:
> 
>  - all links will be broken [2]

IIUC, the problem is that gitlab needs to have a file extension  to make
it correctly serve with HTML content type. All our wiki pages lack a file
extension

It might be possible to achieve this by using sub-directories.

eg instead of converting

 TroubleshootMacvtapHostFail.rst -> TroubleshootMacvtapHostFail.html

do

 TroubleshootMacvtapHostFail.rst -> TroubleshootMacvtapHostFail/index.html

In theory then, if someone accesses

  /TroubleshootMacvtapHostFail

they should get a redirect to

  /TroubleshootMacvtapHostFail/

which should then serve

  /TroubleshootMacvtapHostFail/index.html

>  - changes will need to be reviewed/approved

We could turn off required for merge request approval if really
needed, which would allow any libvirt committer to merge without
waiting, 3rd parties wold still need help. I don't think it is
a big deal though, as the frequency of edits is very small.

>  - low quality/obsolete content is forward-ported as I didn't review
>     anything

Not an issue since we're keeping it separate from main libvirt
docs.

>  - the build script is in bash (This obviously can be changed if somebody
>    cares more than I do.)
> 
> The generator is based on a cleaned up page.xsl and other assets from
> libvirt's repo and the check-html-references script [3] to validate linking.
> 
> The new wiki can for now be browsed from artifacts of the pipeline job that
> I've used to test it:
> 
>  https://pipo.sk.gitlab.io/-/libvirt-wiki/-/jobs/3771076975/artifacts/website/index.html

That's a 404, the right URL seems to be this one (at least this is the
only pipeline I see that exists in your fork)

  https://pipo.sk.gitlab.io/-/libvirt-wiki/-/jobs/3771270309/artifacts/website/index.html

> [1] The conversion was done using a collection of ugly scripts and pandoc.
> Unfortunately markdown-eque formats have the issue of not really having
> strict rules and in certain cases the tools used to process them not
> implementing them correctly. This meant that the least painful was actually
> the coversion from HTML!!! and not the internal mediawiki format.
> 
> [2] If we really want to preserve links I can modify the script to generate
> a list of redirects for the webserver, but I really doubt that preserving
> links has value. Additionally some content was moved to the knowledge base,
> so I really want to just delete it from the wiki, so breaking links is a
> feature.

AFAIK, you can't do redirects in gitlab pages, except the hacky way by
actually creating a page with the desired name, and using the <meta>
tag to redirect when the browser loads it. If you go that far you might
as well just output the content in that page to start with.

With regards,
Daniel
-- 
|: https://berrange.com      -o-    https://www.flickr.com/photos/dberrange :|
|: https://libvirt.org         -o-            https://fstop138.berrange.com :|
|: https://entangle-photo.org    -o-    https://www.instagram.com/dberrange :|