SoK/2021/StatusReport/Suraj Kumar Mahto

Porting docs-kde-org to Hugo

Abstract

docs-kde-org is the central website which hosts the KDE user documentation (development & stable release) in over 25 languages. In this task, I am revamping the old docs website currently hosted at domain docs.kde.org . It uses a python script to fetch the newest version of the documentation from Git (for English) and Subversion (for other languages) and build HTML and PDF files from the DocBook sources. The custom python script is refactored first.

Static site generators like Hugo would be great to shift the current website as it reduces the server dependencies since the website builds only on its updation. Also the use of markdown for content makes the website updation easy even for Contributors who don’t have any prior website maintenance experience. For the site structure similar to now, we are using Docsy Hugo.

The design of the site was quite old and was not responsive for mobile devices. I have also redesigned the site so visitors can get a clear idea of what docs can do for them and how to reach what they want to by making the site easy to navigate.

My aim is to provide it to users/developers in as flexible a form as possible so that people can use it for their personal use cases that they can think of.

Visitors will be able to : - Surf the website and get access to various docs. - get the i18n docs in multiple languages. - Encourage them to contribute to the KDE docs.

Links

Repository:-Documentation Website dev repo
Proposal:-Accepted proposal
Blog - Phase 1:- Blog

Mentors

Work Done

Phase 1

Refactored the python scripts(docgenerator.py) to create markdown files of each category containing json data of all the apps in that category. For example, documentation.md will have

{

 "name": "documentation",
 "apps": [
   {
     "name": "digikam-doc",
     "doc": [
       {
         "latest": "/trunk5/en/digikam-doc/digikam",
         "stable": "/stable5/en/digikam-doc/digikam"
       },
       {
         "latest": "/trunk5/en/digikam-doc/showfoto",
         "stable": "/stable5/en/digikam-doc/showfoto"
       }
     ]
   }
 ]

}

The above thing creates the basic site structure for hugo.
Used and modified layouts from develop-kde-org for docsy hugo layout.

Phase 2

Used the layouts/hig/ (from develop-kde-org docsy) as the default layouts.
Modified the layouts to populate the docbook's paths link.
Implement site wide Search.

Phase 3

Implemented separate pages for each language.
Modified the docgen script to generate separate data for different languages. Now each category file having the json metadata of the respective category is inside content-trans/<lang> respectively for each language.

(MR Link to be merged)

What I've learnt

I worked on a python script that runs at production and manages the whole KDE Documentation.
I learnt to use a python debugger.
Got more command on my web development skills for Hugo.