Refresh and correct API docs using kapidox
Closed, ResolvedPublic

Description

Refresh and correct API docs main pages in KDb, KReport, KProperty, Kexi

Use the frameworks/kapidox tool.

Good example:
https://api.kde.org/frameworks/threadweaver/html/index.html

KDb page:
https://api.kde.org/playground-api/libs-apidocs/kdb/src/html/index.html

staniek created this task.Sep 14 2016, 7:51 PM
staniek updated the task description. (Show Details)Sep 14 2016, 7:56 PM
staniek renamed this task from Refresh and correct API docs main pages to Refresh and correct API docs using kapidox.

Here some proposals for the content of the metainfo.yaml that would setup things as wanted by kapidox (untested, but should work as is).
No logo set will result in a placeholder logo like Phonon has on api.kde.org/ which should be fine for the start.
Please tell which platforms are supported.

If you like I can commit those and ask ochulaud to add all three to the kapidox-based scripts run and also put them on the frontpage of api.kde.org

KProperty:

# kapidox info
description: KProperty is a property editing framework with editor widget similar to what is known from Qt Designer.
#logo: TODO

# TODO: unset those which work
platforms:
    - name: Linux
#    - name: Windows
#    - name: MacOSX
#    - name: Android

public_lib: true
public_source_dirs:
    - src
# kapidox does not expect sources of two libs in the same dir
# so the entry for the cmake/qmake only takes one
#libraries:
#    - cmake: KPropertyCore
#cmakename: KPropertyCore

maintainer:
    - staniek
irc: kexi
mailinglist: kexi-devel

KDb:

# kapidox info
description: KDb is a database connectivity and creation framework, consisted of a general-purpose
 C++ Qt library and set of plugins delivering support for various database vendors.
#logo: TODO

# TODO: unset those which work
platforms:
    - name: Linux
#    - name: Windows
#    - name: MacOSX
#    - name: Android

public_lib: true
public_source_dirs:
    - src
libraries:
    - cmake: KDb
cmakename: KDb

maintainer:
    - staniek
irc: kexi
mailinglist: kexi-devel

KReport:

# kapidox info
description: KReport is a framework for the creation and generation of reports in multiple formats.
#logo: TODO

# TODO: unset those which work
platforms:
    - name: Linux
#    - name: Windows
#    - name: MacOSX
#    - name: Android

public_lib: true
public_source_dirs:
    - src
libraries:
    - cmake: KReport
cmakename: KReport

maintainer:
    - piggz
irc: kexi
mailinglist: kexi-devel
staniek added a comment.EditedSep 21 2016, 10:18 PM

Thanks a lot Friedrich!

For all libs:

  • name: Linux
  • name: Windows
> # kapidox does not expect sources of two libs in the same dir
> # so the entry for the cmake/qmake only takes one
> # libraries:
> #    - cmake: KPropertyCore

As you see there's also KPropertyWidgets. What to do? Is separating them to distinct subdirs enough to get them supported?

When we know how this can be sorted out I am OK with committing.

staniek moved this task from Backlog to Docs on the KEXI board.Jan 27 2018, 9:43 PM

Hi @staniek . While I am currently doing some work to keep api.kde.org alive and cleaning up legacy docs where possible, I remembered this task and would be available to complete it these days :)

First question: do you want the docs to appear in some grouping, like done for Frameworks or KDEPIM? If so, can you provide some text which should be used for the group? And to which of the three repos should the info be added, so which is the most core one by any concept?
Compare how kdepim does it with the group info as given in the metainfo.yaml of the akonadi repo (their most core repo):
https://invent.kde.org/pim/akonadi/-/blob/master/metainfo.yaml#L18

Hi Freidrich. That's a good news to me!

KEXI API docs would be separate ordinary app-level docs, like say, for Marble. Like for Marble, there are some interfaces for plugins.

For KDb, KProperty, KReport it would make sense have a group such as KEXI Frameworks.
In case you need a common place for them, we also have kexi-extras.git repo for storing common files for these frameworks. Currently not in use but planned especially for shared cmake files and our SDC tool.

Thanks for the effort!

@staniek Ah, missed your reply, somehow phabricator did not send me a noticiation.

Let us start here with KDb, KProperty, KReport then. A group named "KEXI Frameworks" seems fine with me.
I will do some review requests for them on the WE, so you can check the data (or try yourself using kapidox locally).

Great, thanks Friedrich.

Respective merge requests are created now here:
https://invent.kde.org/libraries/kdb/-/merge_requests/1
https://invent.kde.org/libraries/kproperty/-/merge_requests/1
https://invent.kde.org/libraries/kreport/-/merge_requests/1

You can generate the combined dox yourself by running kapidox pointed to the parent dir where all three repos have working copies below (symbolic links seems not to work, needs to be real path):

~/path/to/frameworks/kapidox/src/kapidox_generate ~/path/to/parent/of/kdbkpropertykreportsrc

Compare "Generating the documentation" on https://api.kde.org/frameworks/kapidox/html/index.html

Having the two libraries of KProperty documented as one thing is a flaw of kapidox which is an issue for a few other projects as well, including KDE Frameworks modules, but also Akonadi and others. Somebody (will not be me in the near future) hopefully fixes that soon. Showing the docs mixed is all we can do right now, might be better than nothing.

staniek claimed this task.Mar 15 2023, 6:03 PM
staniek closed this task as Resolved.

Done in the Invent