Jump to content

SoK/2021/StatusReport/Suraj Kumar Mahto

From KDE Community Wiki

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.

Links

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.
Retrieved from "https://community.kde.org/index.php?title=SoK/2021/StatusReport/Suraj_Kumar_Mahto&oldid=91597"