https://blogs.kde.org/categories/documentation/Recent content in Documentation on KDE BlogsHugo -- gohugo.ioenTue, 31 Mar 2026 18:04:10 +0300https://blogs.kde.org/2026/01/18/documentation/Sun, 18 Jan 2026 00:00:00 +0000Johnny Jazeixhttps://blogs.kde.org/2026/01/18/documentation/<p><strong>Edit 25/01/2026</strong> documentation.yml is no more used, the documentation is built and published as part of the linux.yml and linux-qt6.yml pipelines. The post is updated to take this in account.</p> <p>For the past few years, generation of user documentation at <a href="https://docs.kde.org/">docs.kde.org</a> was not working. After a few months on working on the related <a href="https://invent.kde.org/websites/docs-kde-org/-/issues/2">issue</a>, we finally managed to make it functional again and it once again displays the documentation for almost 150 applications!</p> <figure> <img class="img-fluid" alt="docs.kde.org website up-to-date" src="https://blogs.kde.org/2026/01/18/documentation/docs-kde-org.png" style="max-width: 100%; height: auto" /> </figure> <h2 id="previous-issues">Previous issues</h2> <p>There were major issues with the previous workflow:</p> <ul> <li>The documentation generation and publication were done on a dedicated machine.</li> <li>It was a monolithic process: the generation of the documentation for all KDE projects was followed with the generation of the website and its publication.</li> <li>Since the arrival of Qt 6, it was not possible to easily update the process to take it into account, so no new documentation was generated.</li> </ul> <p>For ease of maintenance, it would be better if:</p> <ul> <li>Each application took care of generating its own documentation</li> <li>The website generation only cared about retrieving the existing documentation and building the website</li> <li>We could have an easy way to reproduce it locally</li> </ul> <h2 id="current-solution">Current solution</h2> <h3 id="update-suse-qt610-image">Update suse-qt610 image</h3> <p>We use the suse-qt610 docker image to generate the documentation. The different packages needed to build the html/PDF files and generate the website have been <a href="https://invent.kde.org/sysadmin/ci-images/-/blob/b0a9eb931639ff8a45ed30c001164466018982b3/suse-qt610/build.sh#L439-479">installed</a>.</p> <h3 id="generation-of-the-documentation">Generation of the documentation</h3> <p>We have created a new script <a href="https://invent.kde.org/sysadmin/ci-utilities/-/blob/8f721fb820823b46390cdf622f93567f6ddfb7ca/generate-documentation.py">generate-documentation.py</a> that will generate the documentation and publish the documentation for a project to a specific <a href="https://invent.kde.org/teams/ci-artifacts/documentation/-/packages">registry</a>. To ensure the documentation is well-generated, developers need to ensure that their project has:</p> <ul> <li><code>'frameworks/kdoctools': '@latest-kf6'</code> listed in its .kde-ci.yml</li> <li><code>kdoctools_install(po)</code> in its CMakeLists.txt</li> </ul> <h3 id="local-generation">Local generation</h3> <p>To generate locally, you can use the following commands. First retrieve and run the latest image:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">podman pull invent-registry.kde.org/sysadmin/ci-images/suse-qt610:latest </span></span><span class="line"><span class="cl">podman run --user<span class="o">=</span>root -it suse-qt610:latest </span></span></code></pre></div><p>Inside it, clone your repository (the example will use GCompris-teachers handbook):</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">cd</span> builds </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/documentation/gcompris-teachers-handbook </span></span><span class="line"><span class="cl"><span class="nb">cd</span> gcompris-teachers-handbook </span></span></code></pre></div><p>Clone the needed repositories and export the environment variables:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">git clone https://invent.kde.org/websites/docs-kde-org.git docs-kde-org --depth<span class="o">=</span><span class="m">1</span> </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/sysadmin/ci-utilities.git --depth<span class="o">=</span><span class="m">1</span> </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/sysadmin/repo-metadata.git ci-utilities/repo-metadata/ --depth<span class="o">=</span><span class="m">1</span> </span></span><span class="line"><span class="cl"> </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_GITLAB_SERVER</span><span class="o">=</span>https://invent.kde.org/ </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_PACKAGE_PROJECT</span><span class="o">=</span>teams/ci-artifacts/suse-qt6.10 </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_CACHE_PATH</span><span class="o">=</span>/home/user/caches/ </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">CI_COMMIT_REF_NAME</span><span class="o">=</span>master </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">CI_PROJECT_NAME</span><span class="o">=</span>gcompris-teachers-handbook </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">CI_JOB_ID</span><span class="o">=</span><span class="s2">&#34;job_id&#34;</span> </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">DBLATEX_BASE_DIR</span><span class="o">=</span><span class="nv">$PWD</span>/docs-kde-org </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">SGML_CATALOG_FILES</span><span class="o">=</span><span class="nv">$PWD</span>/_install/share/kf6/kdoctools/customization/catalog.xml </span></span></code></pre></div><p><em>Note</em>: we only need the docs-kde-org repository because of PDF generation. There is some work in progress to reduce this dependency.</p> <p>Retrieve the dependencies and build the documentation:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">python3 -u ci-utilities/run-ci-build.py --project <span class="nv">$CI_PROJECT_NAME</span> --branch <span class="nv">$CI_COMMIT_REF_NAME</span> --platform Linux/Qt6/Shared </span></span><span class="line"><span class="cl">python3 ci-utilities/generate-documentation.py --project <span class="nv">$CI_PROJECT_NAME</span> --output-folder webdoc --format html pdf --branch <span class="nv">$CI_COMMIT_REF_NAME</span> --doc-dir _staging/builds/gcompris-teachers-handbook/_install/share/doc/HTML/ </span></span></code></pre></div><p>The output will be in the <code>webdoc</code> folder. You can copy this to your machine using <code>podman cp CONTAINERID:/builds/gcompris-teachers-handbook/webdoc/ .</code> (use <code>podman ps</code> to get the CONTAINERID).</p> <h3 id="website-generation">Website generation</h3> <p>Now that each project generates its own documentation, we have reworked the existing website <a href="https://invent.kde.org/websites/docs-kde-org">scripts</a> to use these files instead of generating all of them again.</p> <p>The <a href="https://invent.kde.org/websites/docs-kde-org/-/blob/master/kdedocs/docretriever.py?ref_type=heads">script</a> will browse all the projects in KDE which have i18n branches in their <a href="https://invent.kde.org/sysadmin/repo-metadata/">metadata</a> and fetch the corresponding documentation (if it exists).</p> <p>The last step is to <a href="https://invent.kde.org/websites/docs-kde-org/-/blob/master/search/do_xapian_index.sh?ref_type=heads">generate the indexes</a> for the website's search feature, using Xapian.</p> <h3 id="local-website-generation">Local website generation</h3> <p>To generate locally, you can use the following commands. First retrieve and run the latest image:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">podman pull invent-registry.kde.org/sysadmin/ci-images/suse-qt610:latest </span></span><span class="line"><span class="cl">podman run --user<span class="o">=</span>root -it suse-qt610:latest </span></span></code></pre></div><p>Inside it, clone the needed repositories and create the needed <code>logs</code> folder:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">cd</span> builds </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/websites/docs-kde-org.git </span></span><span class="line"><span class="cl"><span class="nb">cd</span> docs-kde-org </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/sysadmin/ci-utilities.git --depth<span class="o">=</span><span class="m">1</span> </span></span><span class="line"><span class="cl">git clone https://invent.kde.org/sysadmin/repo-metadata.git ci-utilities/repo-metadata/ --depth<span class="o">=</span><span class="m">1</span> </span></span></code></pre></div><p>You will also need to generate a gitlab token from your <a href="https://invent.kde.org/-/user_settings/personal_access_tokens">invent account</a>. Make sure the <code>read_api</code> scope is selected!</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_GITLAB_SERVER</span><span class="o">=</span>https://invent.kde.org/ </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_GITLAB_TOKEN</span><span class="o">=</span>generated_token </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_PACKAGE_PROJECT</span><span class="o">=</span>teams/ci-artifacts/suse-qt6.10 </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">KDECI_CACHE_PATH</span><span class="o">=</span>/home/user/caches/ </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">PYTHONPATH</span><span class="o">=</span><span class="nv">$PWD</span>/ci-utilities/ </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">CI_COMMIT_REF_NAME</span><span class="o">=</span>master </span></span><span class="line"><span class="cl"><span class="nb">export</span> <span class="nv">CI_PROJECT_NAME</span><span class="o">=</span>docs-kde-org </span></span></code></pre></div><p>Generate the website, copy static files and run the xapian indexing:</p> <div class="highlight"><pre tabindex="0" class="chroma"><code class="language-bash" data-lang="bash"><span class="line"><span class="cl">mkdir -p logs </span></span><span class="line"><span class="cl">./kdedocgen.py -r -s -l doclogconfig.ini -c docgen_conf.ini </span></span><span class="line"><span class="cl">./create_generated_used.php work &gt;website/generated_used.inc.php 2&gt;logs/genused.log </span></span><span class="line"><span class="cl"><span class="nv">KDECI_PACKAGE_PROJECT</span><span class="o">=</span>teams/ci-artifacts/suse-qt5.15 python3 -u ci-utilities/run-ci-build.py --project <span class="nv">$CI_PROJECT_NAME</span> --branch <span class="nv">$CI_COMMIT_REF_NAME</span> --platform Linux/Qt5/Shared --only-setup-environment </span></span><span class="line"><span class="cl"><span class="nv">KDECI_PACKAGE_PROJECT</span><span class="o">=</span>teams/ci-artifacts/suse-qt6.10 python3 -u ci-utilities/run-ci-build.py --project <span class="nv">$CI_PROJECT_NAME</span> --branch <span class="nv">$CI_COMMIT_REF_NAME</span> --platform Linux/Qt6/Shared --only-setup-environment </span></span><span class="line"><span class="cl">cp -R _install/share/doc/HTML/en/kdoctools5-common website/trunk_kf5/en/ </span></span><span class="line"><span class="cl">cp -R _install/share/doc/HTML/en/kdoctools6-common website/trunk_kf6/en/ </span></span><span class="line"><span class="cl">cp -R search/ website/ </span></span><span class="line"><span class="cl">./website/search/do_xapian_index.sh </span></span></code></pre></div><p>The output will be in the <code>website</code> folder.</p> <h3 id="website-deployment">Website deployment</h3> <p>The website repository has its own scheduled pipeline (once a week) to generate the website and publish it.</p> <p>The deployment is done using the <a href="https://invent.kde.org/sysadmin/ci-notary-service">ci-notary</a> service.</p> <h2 id="future-plans">Future plans</h2> <p>There are still multiple issues to tackle:</p> <ul> <li>Most non-ASCII languages (CJK, Arabic...) are not supported for PDF generation. We have two contributors in Season of KDE who will dig into finding a solution to improve this!</li> <li>We have several hardcoded paths/links to Qt 6/KF 6. We need to drop those for when Qt 7/KF 7 comes (<strong>edit 25/01/2026</strong>: this has been handled in this <a href="https://invent.kde.org/sysadmin/ci-utilities/-/commit/d378497a943bc51278764a953e8c85e953f30d22">commit</a>!).</li> <li>Updating deprecated documentation where it makes sense.</li> </ul>https://blogs.kde.org/2024/11/13/api-documentation-porting-sprint/Wed, 13 Nov 2024 00:00:00 +0000Farid Abdelnourhttps://blogs.kde.org/2024/11/13/api-documentation-porting-sprint/<figure> <img class="img-fluid" src="https://blogs.kde.org/2024/11/13/api-documentation-porting-sprint/sprint-port-card.png" style="max-width: 100%; height: auto" /> </figure> <p>It was once said over the <a href="https://mail.kde.org/pipermail/kde-devel/2024-July/002849.html">grapevine</a> that: &quot;Our C++ API documentation has some issues, our QML API documentation has a lot of issues.&quot;</p> <p>And it was true, but that is to change soon! As you might know, there is an ongoing effort to <a href="https://invent.kde.org/teams/documentation/sprints/-/boards">port our documentation</a> from <a href="https://www.doxygen.nl/">Doxygen</a> to <a href="https://doc.qt.io/qt-6/qdoc-index.html">QDoc</a>, and you can help with that.</p> <p>This is a <a href="https://invent.kde.org/teams/goals/streamlined-application-development-experience/-/issues/10">task</a> that has been adopted by the <a href="https://phabricator.kde.org/T17396">Streamlined Application Development Experience</a> championed by <a href="https://nicolasfella.de/">Nicolas Fella</a> and <a href="https://pointieststick.com/">Nate Graham</a> as part of the <a href="https://kde.org/goals/">KDE Goals</a> initiative.</p> <p>We would like to invite you to join our porting sprint effort to finish this task. On <strong>November 14th at 1PM UTC</strong>, we'll be hanging out in the <a href="https://matrix.to/#/%23kde-streamlined-app-dev:kde.org">Matrix room</a> working on this. Hope to see you there.</p> <p><strong>Some prerequisites:</strong></p> <ul> <li>Ability to use a terminal</li> <li>Extra disk space (30GB minimum)</li> <li>Some familiarity with APIs</li> </ul> <p><a href="https://invent.kde.org/teams/goals/streamlined-application-development-experience/-/issues/10#note_1052720">Check out the instructions</a> prepared by <a href="https://rabbitictranslator.com/">Thiago Sueto</a> on how to get started porting a project to QDoc.</p>https://blogs.kde.org/2021/07/30/my-work-documentation-junejuly/Fri, 30 Jul 2021 00:00:00 +0000Schwarzerhttps://blogs.kde.org/2021/07/30/my-work-documentation-junejuly/<p>After two month in documentation I can tell you this: documentation in general is quite alive and kicking. :) From the outside you might see outdated content here and there, but there are quite a few people working on improving that. Of course, as most things, it is a never-ending effort and every helping hand is appreciated. If you are interested in helping, please talk to us on <a href="https://mail.kde.org/mailman/listinfo/kde-doc-english">our mailing list</a>. One of the more time-consuming tasks is currently porting documentation from <a href="https://techbase.kde.org/Welcome_to_KDE_TechBase">TechBase</a> to the new <a href="https://develop.kde.org/">Developer Portal</a>. It's basically copy&amp;paste with some adjustments, so volunteers welcome :)</p> <p>For me the time flew by blazingly fast. In the beginning ... there was Akademy, the first conference for me. It meant getting up at 7 to go to work, joining Akademy when I came back home and staying up till midnight or longer for the last talks or events to finish. Processing and carving out the outcome of the three documentation BoF sessions is still on my todo list.</p> <p>In the time before and since Akademy, I have been busy reading through several years of documentation improvement planning backlog and fixing lots of smaller issues in existing docs in the wikis and on the new Developer Portal. This also included cleaning up some outdated content (EBN has been decommissioned) and proofreading other people's documentation-related merge requests when asked to do so.</p> <p>Unfortunately, <a href="https://invent.kde.org/websites/volunteers-akademy-kde-org/-/merge_requests/1">my first contribution to one of the website's Git repositories</a> is still unmerged at the time of writing. I blame me for that not keeping track of my own merge requests. But it also shows one of the things we need to put more effort into: closing merge requests (one way or another). Also, check your own merge requests once in a while. You can do that by using the following URL and putting you account name at the end: <a href="https://invent.kde.org/dashboard/merge_requests?scope=all&amp;state=opened&amp;author_username=">https://invent.kde.org/dashboard/merge_requests?scope=all&state=opened&author_username=</a><b>your_user_name</b></p> <p>For some projects (e.g. KApiDox there had been several merge requests open for a year or longer. One was a data loss issue when generating api documentation from the parent folder (..). <a href="https://invent.kde.org/frameworks/kapidox/-/merge_requests/17">Adriaan was so kind to fix that</a> even if only because he wanted me to stop nagging. ;) These open merge requests and some open issues are now merged with only one merge request remaining which will probably be replaced by a new one from last week: <a href="https://invent.kde.org/frameworks/kapidox/-/merge_requests/20">preparing KApiDox to be run in a docker container</a>. That one I am working on with a friend with stronger Python and Docker foo.</p> <p>Another issue with KApiDox was that it could not be run locally anymore due to restrictions on fetching KDE accounts information from SVN. <a href="https://invent.kde.org/frameworks/kapidox/-/merge_requests/19">I changed that accounts parsing behaviour</a> to be an optional command line switch <a href="https://invent.kde.org/websites/quality-kde-org/-/merge_requests/2">which is run on api.kde.org</a> but not locally. You are still free to fetch the KDE accounts file manually and point KApiDox to it.</p> <p>But while tooling was my main scope during that first time, it's not what I actually wanted to do. It just jumped in my way. :) So I also collected opinions, topics and ideas for the actual documentation. These days I am starting to write porting notes meant mainly for third-party developers who will start porting their KF5 applications to KF6 soon. More on that one later.</p> <p>To conclude these first two months, I can say, wherever you look, you will find issues to fix, things to improve, content to update ... And many of these things are not hard to do. So if you ever wondered how you could start contributing to KDE, documentation is great place to start. :)</p>