Re: KApiDox move from dedicated server to Jenkins

[Ben Cooksley]

On Sat, Sep 11, 2021 at 5:24 AM Frederik Schwarzer 
wrote:

> Hi,
>

Hi all,


> we have been working on getting KApiDox to run on Jenkins. This work has
> been taken way longer than I expected but has now reached a state close
> to finished. :)
>
> So I would like to invite you to check https://api-dev.kde.org/ for any
> show stoppers.
>
> Known issues (not show stoppers):
>
> - For now the Maintainers field defaults to "KDE Developers" for
> potential GDPR violation reasons, which needs to be figured out later.
>
> - Some modules contain formatting issues regarding markdown code blocks.
> These are also there in the current system and need to be checked at
> some point.
>
> - The "Older versions" links are broken. Since those docs are not
> generated anymore, we need to figure out a way to have them available
> statically.
>

I've now completed transferring a copy of all of the Older API
Documentation to https://api-dev.kde.org/legacy/
This is aliased in from elsewhere on the server, so it's contents won't be
disturbed by the automatic generation process we have for new KApiDox based
documentation.

I also included the legacy CMake documentation when setting that up.

If we could please update the front page to point there that should resolve
this point.


> If we do not see any bigger issues, I would like to go live with the new
> system in a week or two.
>
> Thanks for your help.
>
> CHeers,
> Frederik
>

Cheers,
Ben

Re: KApiDox move from dedicated server to Jenkins

[Ben Cooksley]

On Sat, Sep 11, 2021 at 7:43 AM Friedrich W. H. Kossebau 
wrote:

> Am Freitag, 10. September 2021, 19:23:47 CEST schrieb Frederik Schwarzer:
> > Hi,
> >
> > we have been working on getting KApiDox to run on Jenkins. This work has
> > been taken way longer than I expected but has now reached a state close
> > to finished. :)
>
> Congrats on moving forwards, thanks for the work.
>
> Linking to external docs (mainly the Qt ones) seems missing. For that
> respective doxygen tags files need to be added. Qt generates such files
> during
> the build, so for the current api.kde.org people copied those tags files
> from
> their distribution's package.
>
> Here I did for updating to Qt 5.15:
> https://invent.kde.org/websites/quality-kde-org/-/commit/
> 8a18c9033751cb41548361aea5c8ba2de3499dd7
>
> with the files found in /usr/share/doc/packages/qt5/*/*.tags, provided by
> the
> package libqt5-qtdoc-devel on openSUSE TW.
>

> To see how kapidox is instructed about those tags files, as that seems
> missing
> from its own docs, see the usage example in the current api.kde.org
> scripts:
> https://invent.kde.org/websites/quality-kde-org/-/blob/master/apidox/src/
> kapidoxgendox.sh#L33
> 
>

Thanks for the details on this.

I've now copied over those same tags and tweaked the pipeline we run on
Jenkins which should solve that.


> CHeers
> Friedrich
>
>
Cheers,
Ben

Re: KApiDox move from dedicated server to Jenkins

[Friedrich W. H. Kossebau]

Am Freitag, 10. September 2021, 19:23:47 CEST schrieb Frederik Schwarzer:
> Hi,
> 
> we have been working on getting KApiDox to run on Jenkins. This work has
> been taken way longer than I expected but has now reached a state close
> to finished. :)

Congrats on moving forwards, thanks for the work.

Linking to external docs (mainly the Qt ones) seems missing. For that 
respective doxygen tags files need to be added. Qt generates such files during 
the build, so for the current api.kde.org people copied those tags files from 
their distribution's package.

Here I did for updating to Qt 5.15:
https://invent.kde.org/websites/quality-kde-org/-/commit/
8a18c9033751cb41548361aea5c8ba2de3499dd7

with the files found in /usr/share/doc/packages/qt5/*/*.tags, provided by the 
package libqt5-qtdoc-devel on openSUSE TW.

To see how kapidox is instructed about those tags files, as that seems missing 
from its own docs, see the usage example in the current api.kde.org scripts:
https://invent.kde.org/websites/quality-kde-org/-/blob/master/apidox/src/
kapidoxgendox.sh#L33

CHeers
Friedrich

Re: Re : KApiDox move from dedicated server to Jenkins

[Ben Cooksley]

On Sat, Sep 11, 2021 at 5:40 AM Carl Schwan  wrote:

> Le vendredi 10 septembre 2021 à 7:23 PM, Frederik Schwarzer <
> schwar...@kde.org> a écrit :
>
> > Hi,
>
> Hi :D
>

Hey Carl,


> > we have been working on getting KApiDox to run on Jenkins. This work has
> > been taken way longer than I expected but has now reached a state close
> > to finished. :)
> >
> > So I would like to invite you to check https://api-dev.kde.org/ for any
> > show stoppers.
>
> Great work :D
>
> I see on an issue that I would qualify as blocking and it's the lack of the
> ECM generated doc: https://api-dev.kde.org/ecm. We are also losing the
> kube/sink doc (located at api.kde.org/doc/sink) but it's also available
> in readthedocs and ihmo it should be in Doxygen format.
>

My understanding is that ECM uses something other than Doxygen for
generating it's API Documentation, which is why it is absent.

Would anyone on the list know if it is possible to get this process to use
Doxygen, or if we need to put in place a mechanism explicitly for ECM?


> We also are losing the krita/kmymoney/other app private api generation,
> but that maybe can be generated in another ci pipeline later. Not sure how
> much thses apps' developers are using it.
>

This can likely be rectified if needed by including them within
https://invent.kde.org/sysadmin/binary-factory-tooling/-/blob/master/apidocs/repos-to-process


> On the upside, I see that mauikit doc is finally correctly generated using
> qdoc. Yeah \o/
>

Yes, the new setup allows us to provide this now - and being Docker image
based for the generation phase should make future updates easier as well as
needed.


> Cheers,
> Carl
>

Thanks,
Ben

>
> > Known issues (not show stoppers):
> >
> > -   For now the Maintainers field defaults to "KDE Developers" for
> > potential GDPR violation reasons, which needs to be figured out
> later.
> > -   Some modules contain formatting issues regarding markdown code
> blocks.
> > These are also there in the current system and need to be checked at
> > some point.
> > -   The "Older versions" links are broken. Since those docs are not
> > generated anymore, we need to figure out a way to have them available
> > statically.
> >
> > If we do not see any bigger issues, I would like to go live with the
> new
> > system in a week or two.
> >
> > Thanks for your help.
> >
> > CHeers,
> > Frederik
>

Re: KApiDox move from dedicated server to Jenkins

[Ben Cooksley]

On Sat, Sep 11, 2021 at 5:24 AM Frederik Schwarzer 
wrote:

> Hi,
>
> we have been working on getting KApiDox to run on Jenkins. This work has
> been taken way longer than I expected but has now reached a state close
> to finished. :)
>
> So I would like to invite you to check https://api-dev.kde.org/ for any
> show stoppers.
>
> Known issues (not show stoppers):
>
> - For now the Maintainers field defaults to "KDE Developers" for
> potential GDPR violation reasons, which needs to be figured out later.
>
> - Some modules contain formatting issues regarding markdown code blocks.
> These are also there in the current system and need to be checked at
> some point.
>
> - The "Older versions" links are broken. Since those docs are not
> generated anymore, we need to figure out a way to have them available
> statically.
>

I already have a plan for this - don't worry about that one :)


> If we do not see any bigger issues, I would like to go live with the new
> system in a week or two.
>
> Thanks for your help.
>
> CHeers,
> Frederik
>

Cheers,
Ben

Re: KF API Documentation proposed, small, addition

[Ahmad Samir]

On 09/09/2021 23:34, Friedrich W. H. Kossebau wrote:

Am Donnerstag, 9. September 2021, 23:23:29 CEST schrieb Ahmad Samir:

On 09/09/2021 22:47, Friedrich W. H. Kossebau wrote:

Am Donnerstag, 9. September 2021, 22:35:05 CEST schrieb Ahmad Samir:

On 09/09/2021 22:24, Friedrich W. H. Kossebau wrote:

Am Donnerstag, 9. September 2021, 21:45:33 CEST schrieb Ahmad Samir:

On 30/08/2021 16:35, Friedrich W. H. Kossebau wrote:

Thanks for pushing this here.

Am Montag, 30. August 2021, 14:17:42 CEST schrieb Ahmad Samir:
Open question:
in which places is it a good idea to use "code"-style with class names
and
method names? So when does readability suffer by too many changes in
the
formatting in a text body?

Looking e.g. at the Qt docs for a reference, they do not use
"code"-style
when referencing classes or methods from text, as well as in the
listing
of classes and methods. So I wonder if this is by design or just
historic?


They use QDoc, IIUC; and it looks like they recommend using \c
https://doc.qt.io/qt-5/04-qdoc-commands-textmarkup.html

at least that page suggests so.


Then our question was not "if" they have a command to markup things to
be
printed code-like, but "when" it should be used. And the examples they
give
(not sure though if exclusive or inclusive) are

"
variable names, user-defined class names, and C++ keywords (for example,
int and for)
".

So no mention of names of the methods, members, properties and classes
the
documentation is about (note the "user-defined"). And looking at the
existing Qt API documentation, I would guess the given list is rather
exclusive then, and \c with Qt is not to be used when referencing the
elements of the documented API itself (at least in flow text).

Myself I meanwhile rather think that this might be a good choice.
Imagine
how e.g. https://doc.qt.io/qt-6/qstring.html would look like if all text
elements referencing Qt classes or method names would be in code-style.
I
guess the reading flow in the flow text blocks would suffer a lot.


So one vote for and one vote against, we need a tie-breaker.


What I would like to see are some argument for why you want this change?
What is broken now, what does it improve?
Can you give an example where your proposal is applied and what the result
is, before and after?


I think it's useful to markup the method names, that makes reading the API
docs in text format in a header file easier, the same way marking up
true/false is useful, the same way syntax highlighting in most text editors
is useful.


I see, that is where you are coming from, it makes some sense there. But...

... it only makes sense for people looking at headers in a plain text editor
which also is capable of parsing doxygen comments and adding respective
highlighting.

.. for every other plain text viewers/editors, including on the gitlab file
viewer, it makes things harder to read.



I don't see how it's harder to read the API docs than '@c true' or '@param'
or any other doxygen command when viewed in an editor that doesn't highlight doxygen syntax 
properly; those same editors highlight C++ code properly?



.. it very possibly lowers the quality of the generated API docs, which should
be the main purpose of writing those API documentation snippets, no?

So im summary not convinced this would be a change for the better.

Cheers
Friedrich




Since no one else seems to care either way, I'll drop the matter.

Regards,
Ahmad Samir

Re : KApiDox move from dedicated server to Jenkins

[Carl Schwan]

Le vendredi 10 septembre 2021 à 7:23 PM, Frederik Schwarzer  
a écrit :

> Hi,

Hi :D

> we have been working on getting KApiDox to run on Jenkins. This work has
> been taken way longer than I expected but has now reached a state close
> to finished. :)
>
> So I would like to invite you to check https://api-dev.kde.org/ for any
> show stoppers.

Great work :D

I see on an issue that I would qualify as blocking and it's the lack of the
ECM generated doc: https://api-dev.kde.org/ecm. We are also losing the
kube/sink doc (located at api.kde.org/doc/sink) but it's also available
in readthedocs and ihmo it should be in Doxygen format.

We also are losing the krita/kmymoney/other app private api generation,
but that maybe can be generated in another ci pipeline later. Not sure how
much thses apps' developers are using it.

On the upside, I see that mauikit doc is finally correctly generated using
qdoc. Yeah \o/

Cheers,
Carl
>
> Known issues (not show stoppers):
>
> -   For now the Maintainers field defaults to "KDE Developers" for
> potential GDPR violation reasons, which needs to be figured out later.
> -   Some modules contain formatting issues regarding markdown code blocks.
> These are also there in the current system and need to be checked at
> some point.
> -   The "Older versions" links are broken. Since those docs are not
> generated anymore, we need to figure out a way to have them available
> statically.
>
> If we do not see any bigger issues, I would like to go live with the new
> system in a week or two.
>
> Thanks for your help.
>
> CHeers,
> Frederik

KApiDox move from dedicated server to Jenkins

[Frederik Schwarzer]

Hi,

we have been working on getting KApiDox to run on Jenkins. This work has 
been taken way longer than I expected but has now reached a state close 
to finished. :)


So I would like to invite you to check https://api-dev.kde.org/ for any 
show stoppers.


Known issues (not show stoppers):

- For now the Maintainers field defaults to "KDE Developers" for 
potential GDPR violation reasons, which needs to be figured out later.


- Some modules contain formatting issues regarding markdown code blocks. 
These are also there in the current system and need to be checked at 
some point.


- The "Older versions" links are broken. Since those docs are not 
generated anymore, we need to figure out a way to have them available 
statically.


If we do not see any bigger issues, I would like to go live with the new 
system in a week or two.


Thanks for your help.

CHeers,
Frederik

Reminder: Weekly KF6 Meeting

[Volker Krause]

Hi everyone,

please remember the weekly KF6 meeting, every Monday 15:00 UTC / 17:00 CEST on 
https://meet.kde.org/b/ada-mi8-aem!

I'm sure you don't want to let poor Alex end up all alone in the meeting room 
with all his burning questions blocking his Frameworks work going unanswered 
again, do you? ;)

Thank you,
Volker

signature.asc
Description: This is a digitally signed message part.