Re: Re : KApiDox move from dedicated server to Jenkins

[Ben Cooksley]

On Sun, Sep 12, 2021 at 7:07 AM Frederik Schwarzer 
wrote:

> Hi,
>

Hi all,


> On 9/10/21 21:17, Ben Cooksley wrote:
> > On Sat, Sep 11, 2021 at 5:40 AM Carl Schwan  wrote:
>
> >> 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
>
> So, we would need to decide whether we want to have applications that
> only have private APIs documented?
>

That is correct.


> Where do we draw the line currently?
>

To date we've not really drawn a line anywhere, but in general I think it
would be best for us to only include API Documentation for projects that
people can actually use externally of the project itself.
(so for Applications, they would need to provide a plugin interface, or a
library that lets people reuse components of it)

Otherwise people might be confused as to what they're looking at.


> In general I would say, just generate everything that has a Doxyfile ...
> but there might be good reasons against that regarding processing power?
>

In the past that has meant that build runs of API Documentation took
several hours.

I'd also recommend taking a look at it from a maintainability point of view
as this is something that will continue to run for some time, so we need to
ensure that if projects do have special requirements that they do not
create issues from that perspective.


> Cheers,
> Frederik
>

Cheers,
Ben

Re: Re : KApiDox move from dedicated server to Jenkins

[Frederik Schwarzer]

Hi,

On 9/10/21 21:17, Ben Cooksley wrote:

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



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


So, we would need to decide whether we want to have applications that 
only have private APIs documented?


Where do we draw the line currently?

In general I would say, just generate everything that has a Doxyfile ... 
but there might be good reasons against that regarding processing power?


Cheers,
Frederik

Re: Re : KApiDox move from dedicated server to Jenkins

[Frederik Schwarzer]

Hi,

On 9/10/21 19:39, Carl Schwan wrote:


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.


Thanks for the list. I will look into those.



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


mauikit produces some warnings, in case someone wants to fix those (or 
tone down the warning level):

https://binary-factory.kde.org/job/Generate_API_Documentation/13/consoleFull

There are also other warnings and errors, I will look at soon. Those are 
secondary though, as in they have been there before.


Cheers,
Frederik

Re: KApiDox move from dedicated server to Jenkins

[Frederik Schwarzer]

Hi,

On 9/11/21 00:30, Ben Cooksley wrote:


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.


For me it makes more sense to keep the link to api.kde.org because once 
we switch to the new system, we would have to change that link again.


Now with all the files in place (thanks for that :)) the links will just 
continue to work.


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,
>

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 : 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