Documentation revamp update

[Nicolas Fella]

Am 04.04.25 um 17:24 schrieb Méven:
> Hi,
>
> > I'm happy to announce a major milestone in our effort to improve our API
> documentation website by porting it to QDoc.
>
> Great \o/
>
> > Please have a look and report any issues. We do have some flexibility
> regarding content and appearance, but please understand that we have to
> work within what QDoc provides, so we might not be able to accommodate
> all requests easily.
>
> The root page is very tall, maybe we could have some table to display 
> libraries in in two columns per tier.
> Or we could have a menu with links to tiers sections.

In principle we could replicate https://doc.qt.io/qt-6/index.html, it's 
"just" a matter of applying some CSS. Unfortunately their stylesheets 
are not part of the upstream Qt repos.


> In https://api-staging.kde.org/kservice-index.html
> KService links does not link to https://api-staging.kde.org/kservice.html

Yeah that's an unfortunate side-effect of how QDoc resolves links. I 
tried to work around it but couldn't make it work.


>
> The site icon (favicon) is Qt's, surely we can do something about it.
> Please not the same icon as the one on https://invent.kde.org

This should be fixed with the next site rebuild


> We have since mentions dating way back. For instance: 
> https://api-staging.kde.org/kwindowsystem.html
> We might want to remove those from KF5, maybe not in code, but at 
> least in doc.
> Or New/recent API could be highlighted. Like having some style to 
> differentiate the recency of the since might be nice.
> Or that'd be for the code change phase or later.

QDoc has a global switch to ignore the since information before a given 
version. I have now set this to 6.0


>
> This feels very nice, to have the same navigation and style as Qt's 
> doc, and links back to Qt's doc when their classes are mentioned.
>
> > One major thing that's currently missing is a search function.
>
> Great to hear there is yet some effort going on. This feels like an 
> important missing piece.

There is some ideas on 
https://invent.kde.org/teams/documentation/sprints/-/issues/81, but it 
needs somebody to step up and finish it, otherwise we'll have to launch 
without a search bar.

Note that you can still search via "site:api-staging.kde.org Foo" in 
your favorite search engine.


>
> > Thanks to everyone who contributed to this effort!
>
> Thanks to all of you and Nicolas.
>
> Le ven. 4 avr. 2025 à 14:53, Nicolas Fella <nicolas.fella at gmx.de> a 
> écrit :
>
>     Hi,
>
>     I'm happy to announce a major milestone in our effort to improve
>     our API
>     documentation website by porting it to QDoc.
>
>     We now have a preview of the new site available at
>     https://api-staging.kde.org/, with all Frameworks converted to the new
>     syntax.
>
>     Please have a look and report any issues. We do have some flexibility
>     regarding content and appearance, but please understand that we
>     have to
>     work within what QDoc provides, so we might not be able to accommodate
>     all requests easily.
>
>     One major thing that's currently missing is a search function. There's
>     some thoughts and a WIP at
>     https://invent.kde.org/teams/documentation/sprints/-/issues/81. Help
>     with this and other web-development topics is welcome.
>
>     Currently the documentation syntax changes for the frameworks are in a
>     separate branch, we will merge these to master as we are going
>     live with
>     the new site.
>
>     The current plan is to go live with Frameworks only once the site is
>     ready, other libraries can be converted/added over time.
>
>     You can find some instructions about converting in
>     https://invent.kde.org/-/snippets/3206
>
>     Thanks to everyone who contributed to this effort!
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.kde.org/pipermail/kde-devel/attachments/20250505/d959920e/attachment.htm>