Docs.krita.org has been switched to sphinx!

[Wolthera]

On Sun, May 27, 2018 at 4:09 PM, Boudewijn Rempt <boud at valdyas.org> wrote:
>
> On zondag 27 mei 2018 15:09:21 CEST Wolthera wrote:
> > Hey everyone,
> >
> > https://docs.krita.org/ has been moved to sphinx, this technology switch
> > means that we'll be able to provide offline copies, translation
> > possibilities and in general the pages will be faster and safer due to
> > being static with a little whiff of javascript for using the search.
> >
> > You can thus now go to https://docs.krita.org/fr/KritaFAQ.html for the
> > French version of the FAQ, and for the english language epub you can
> > currently go to https://docs.krita.org/en/epub/KritaManual.epub
> >
> > Now, there's a lot of things that need discussing. To the point I am not
> > sure if the meeting of tomorrow will be sufficient. Things I cannot figure
> > out by my own:
> >
> > 1. 404 pages. All the old links won't work anymore, and we don't even have
> > a custom 404 page. How should we go about resolving this.
>
> I guess we can easily get one, that explains the move.
>
> > 2. How should we decide upon a draft/proofingreading workflow?
>
> Let's use phabricator for that, in principle? I guess there are people who
> should just commit and push, like you, but others probably want to have their
> changes looked at. Maybe Irina likes to do some proof reading?

Well, my English is not perfect, and there's still a ton of pages which have not
been formally proofread, so I am worried about those pages too.

>
> > 3. How should we decide the translation process.
> >    The translation process is to generate pot files with gettext, then to
> > generate po files, have those translated, and then sphinx can generate mo
> > files and use those for a language specific build.
> >    3.1. Where should the PO files go?
>
> I think we should put that question to the i18n-doc list.
>
> >    3.2. Maybe we should remove certain pages(contributor's manual) from the
> > POT files with some kind of script?
>
> Good point...
>
> >    3.3. Where do we want the epubs to go, and should we try to name them
> > according to language?
>
> Maybe even more importantly: where shall we make them available for download?

Those are basically two parts of the same question: how to make
sensible links to given versions of the manual
that make it super clear which manual version something is to the user? :D

> > 4. Protocol for removing pages.
>
> That should always be a diff on phabricator, I think. It shouldn't be
> something people can do on a whim.

I was more wondering about things like, first we deprecate a page and
then we remove it.

But if we do that, what kind of rules should we create for when a page
really needs to go?

Like, if the minor version is different, should it be removed?

>
> > 5. EPUB files are build by jenkins too. I've configured the conf.py so that
> > we get git commit hashes in the EPUB identifier and the html footer when
> > you build locally, but Jenkins doesn't have access to the git commit for
> > technical reasons(only the build url). How do we figure out which version
> > of the manual the epub is build on when its made by jenkins?
>
> That I don't know...

Well, right now if you build locally it prints the following:
<dc:identifier id="krita_manual_build_fullgithash">https://krita.org/</dc:identifier>

in Jenkins this becomes

<dc:identifier id="krita_manual_build_6">https://krita.org/</dc:identifier>

And if it cannot find a build id or hash it'll instead write
krita_manual_build_4.0.3.

What we could do is that Jenkins builds always link to the build url
instead of krita.org

<dc:identifier id="krita_manual_jenkins_build_6">https://binary-factory.kde.org/job/Website_docs-krita-org/6/</dc:identifier>

while local builds will be

<dc:identifier id="krita_manual_fullgithash">https://krita.org/</dc:identifier>

and if neither git nor jenkins id can be found.

<dc:identifier id="krita_manual_release">https://krita.org/</dc:identifier>

Is this a sensible idea? Is there anything else we could do?

-- 
Wolthera