On Thu, Jan 15, 2026 at 12:35 AM Luigi Toscano <[email protected]> wrote:
> Benson Muite ha scritto: > > On Wed, Jan 14, 2026, at 1:42 PM, Johnny Jazeix wrote: > >> Hi, > >> > >> Since we restored docs.kde.org, I would like to propose to add a new > >> item in the checklist [1] for new projects (rewording welcome if > >> needed): > >> - [ ] User documentation in docbook format should exist in a doc (or > >> docs) folder > > > > Docbook is nice and can be converted to html for web or viewed > > directly using desktop applications. Would authoring in other formats > > and converting to Docbook also be allowed? For example Sphinx > > uses ReStructured Text which can be converted to DocBook, TexInfo > > can also be converted to DocBook. > > Right now, the source format used by khelpcenter and docs.kde.org is > docbook. > A few bigger manual uses sphinx, (digikam, kdenlive, krita, kstars) but > that > require a specialized site and I would consider that an exception and not > the > rule for now. > Sphinx is not ideal for a number of reasons - as the more translated strings a Sphinx site has the slower the build process goes, and by quite a significant margin. It takes about 1 hour 20 minutes to generate the Kdenlive documentation for instance (while just untranslated English is only a couple of minutes, and it only handles 12 other languages in those 80 minutes). So before we can support Sphinx, we would have to re-work / re-write it's translation support completely to make it scalable. We also generate man pages from docbook, I would definitely rule out > TexInfo. > If/when we manage to pull enough work to support sphinx in kdoctools we can > consider sphinix as regular, but not right now. > > > -- > Luigi > Cheers, Ben
