KDE Developer portal

[Carl Schwan]

Hello everyone,

Some of you probably saw the "First-class user & developer documentation centralized on a portal" goal proposal by Isadora one year ago (https://phabricator.kde.org/T11096). I shared Isadora's opinion, of having a good developer portal with all the information on how to use the KDE Frameworks, could help with third-parties' use of them, and also help with the onboarding of new developers.

Sadly it wasn't voted but in the same direction, I experiment with creating such a developer portal for KDE using the static site generator Hugo and the docsy theme. The result with a few converted articles can be seen here: http://kde.carlschwan.eu/docs/.

Current advantages of docsy and Hugo over the current Mediawiki install at techbase.kde.org are:

* It is possible to have code examples that can be compiled and shared as tars. This make it easier to have an automatic test ensuring that the code in the examples works.
* The content gets automatically organized in section and with easy navigation between the sections.
* It is also possible to create promotional content of our developer libraries and tools as can be seen here http://kde.carlschwan.eu (I need to put more work on it), news pages, and other types of pages.
* It is possible to host multiple separate documentation on the same instance so that it could be possible in the future to move stuff like docs.plasma-mobile.org and hig.kde.org to the same instance so that search would work across the projects.
* One less wiki instance to maintain (there are pains to maintain and update).

Moving from a Wiki also has some disadvantages, first, we need to port all the content but it would be a good occasion to update them to Qt5 and KF5. This will be a lot of work so help will be needed. And it will make it slightly more difficult to contribute since unlike a wiki it uses git, but in the sidebar, a link is included and directly open the GitLab web editor for the open webpage.

There is also the possibility to move to Sphinx, as some other KDE projects did, and I have a small demo here: https://invent.kde.org/carlschwan/techbase-kde-org. Problems with sphinx are that the theming isn't easy and it is a lot more difficult to create great promotional content with it. It also has a small advantage that a Doxygen integration already exists, so it easy to link to api.kde.org classes and methods but I have an idea of how to create a similar integration in Hugo.

So my question now to the community is the effort worth it? and who would like to work on it with me? ;) It doesn't necessarily need technical knowledge, but we need to work on the promotional content, porting the old articles to a similar but different format, updating them to Qt5 and KF5 (and maybe also writing new articles about Kirigami/Android/... for examples).

Cheers,
Carl

PS: The dark theme is broken, I know already :(