[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[bcooksley (Ben Cooksley)]

bcooksley added a comment.


  At this point i'd suggest simply going ahead with the short term pain, long 
term gain method of adopting KApiDox for building your API Documentation, as 
the legacy scripts and mechanisms are fragile - I certainly don't want to touch 
them.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: bcooksley
Cc: piggz, kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, 
staniek, blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  In https://phabricator.kde.org/T3755#55509, @kossebau wrote:
  
  >
  
  
  
  
  > @staniek I would recommend to move src/Mainpage.dox to the toplevel dir 
(and adopting the EXCLUDE entry). Because right now this results in the 
additional subsection "Kexi" on 
https://api.kde.org/bundled-apps-api/kexi-apidocs/ without any use.
  
  OK thanks Friedrich.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: piggz, kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, 
staniek, blazquez

Re: [Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jaroslaw Staniek]

On 20 September 2016 at 12:08, Adam Pigg  wrote:

> Are the Kexi plugins libs not part of a public Kexi API?
> ​
>
> ​Public within Kexi, yes. Public so that independent vendors distribute
own extensions? Not quite, that's not maintained.

To save the overhead we're distributing all plugins that depend on Kexi
with Kexi releases[1]. Except for complex cases such as form maps widget or
web browser widget, that are truly optional and have larger dependencies,
plugins are not even in separate packages because it's hard to think of
Kexi without forms, queries or tables installed. In theory it makes sense
but we don't get any benefit from it. It's like having browser not
supporting sound. It's possible but not practical.

​> ​Also, the Kexi specific parts of the report plugin scripting side
should be documented as user api

Yes, hopefully as much as possible was moved to KReport (or maybe more can
be moved?).
​
The above does not mean we're not encouraging development of plugins.
Plugins would be even possible to write in the future scripting language
that we plan to support (Javascript).

I am just wondering why docs for Kexi plugin developers's docs shall not be
just a step or two away from the Kexi developer's (contributors) docs, not
more. Obviously in a separate Doxygen group, but not within in separate web
site (api.kde.org vs kexi-project.org).

[1] A note for others, Since version 3, database plugins moved to the KDb
project, KProperty plugins are compiled in but sit in the KProperty
project, and report element plugins moved to the report KReport; all these
plugins are not dependent on Kexi anymore and are distributed separately,
even if we happen to have combined releases like the current Beta.


> On Tue, 20 Sep 2016, 09:37 staniek (Jarosław Staniek), <
> nore...@phabricator.kde.org> wrote:
>
>> staniek added a comment.
>>
>> The domain name is secured and it's KDE's already.
>>
>> *TASK DETAIL*
>> https://phabricator.kde.org/T3755
>>
>> *EMAIL PREFERENCES*
>> https://phabricator.kde.org/settings/panel/emailpreferences/
>>
>> *To: *staniek
>>
>> *Cc: *kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin,
>> staniek, blazquez
>>
>


-- 
regards, Jaroslaw Staniek

KDE:
: A world-wide network of software engineers, artists, writers, translators
: and facilitators committed to Free Software development - http://kde.org
Calligra Suite:
: A graphic art and office suite - http://calligra.org
Kexi:
: A visual database apps builder - http://calligra.org/kexi
Qt Certified Specialist:
: http://www.linkedin.com/in/jstaniek

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[kossebau (Friedrich W. H. Kossebau)]

kossebau added a comment.


  In https://phabricator.kde.org/T3755#55412, @staniek wrote:
  
  > Are we sure?
  >
  > For example KDevelop has kdevplatform 
https://api.kde.org/extragear-api/kdevelop-apidocs/index.html, just released 
yesterday, but Calligra does not:
  >
  > https://api.kde.org/bundled-apps-api/calligra-apidocs/
  
  
  This is because the pages generated below kdevelop-apidocs include both repos 
kdevelop and kdevplatform. The script there is not run on each repo separately, 
but run at the checkout of both.
  But only kdevplatform has a Mainpage.dox file. So by that old kdelibs script 
system of just generating documentation for things in the folders below the 
deepest Mainpage.dox files this results in what can be seen.
  
  The script also used to do the same before with the repos krita, kexi & 
calligra, generating all documentation for all of them in one go below 
calligra-apidocs.
  Which of course resulted in a mess, due to the forked classes and also was 
wrong with krita no longer being a Calligra project.
  So @winterz on my request changed the setup to generate the documentation for 
all three repos separately. Due to kexi having KUndo duplicated and also having 
a different code layout, I decided against still generating kexi & calligra 
docs together.
  
  The only thing still missing for that setup is being listed on 
https://api.kde.org/other.php
  
  But indeed this is just for now, as intermediate solution. Someone  needs to 
look into a future-proof setup for the separate contributor-oriented complete 
source-code covering generation of API dox. Not me, too much to do already, 
only available for giving over-smart comments ;)
  
  @staniek I would recommend to move src/Mainpage.dox to the toplevel dir (and 
adopting the EXCLUDE entry). Because right now this results in the additional 
subsection "Kexi" on https://api.kde.org/bundled-apps-api/kexi-apidocs/ without 
any use.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: kossebau
Cc: piggz, kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, 
staniek, blazquez

Re: [Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Adam Pigg]

Are the Kexi plugins libs not part of a public Kexi API?  Also, the Kexi
specific parts of the report plugin scripting side should be documented as
user api

On Tue, 20 Sep 2016, 09:37 staniek (Jarosław Staniek), <
nore...@phabricator.kde.org> wrote:

> staniek added a comment.
>
> The domain name is secured and it's KDE's already.
>
> *TASK DETAIL*
> https://phabricator.kde.org/T3755
>
> *EMAIL PREFERENCES*
> https://phabricator.kde.org/settings/panel/emailpreferences/
>
> *To: *staniek
>
> *Cc: *kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin,
> staniek, blazquez
>

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  The domain name is secured and it's KDE's already.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[ochurlaud (Olivier Churlaud)]

ochurlaud added a comment.


  @bcooksley  can correct me if I'm wrong, but if you want to have the website 
under the kde umbrella, come with a new website, open a ticket to have a domain 
name like the ones you named, and //Sail for Adventure//. =)

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: ochurlaud
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  Very good, either solution that declutters the API pages would work for me. 
So the question is where to generate project's docs.
  
  Generating from within kexi-project.org comes to my mind, what would be 
feasible as part of a larger challenge: (finally) moving the site to the KDE's 
infrastructure. @ochurlaud @bcooksley would you think we can initiate this 
move? kexi-project.org is currently a set of static files only, very old and 
causing confusion; these shall be replaced with something closer to 
marble.kde.org or kate-editor.org.
  If OK I can create ticket and we can mark this as LATER.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[ochurlaud (Olivier Churlaud)]

ochurlaud added a comment.


  > Hiding the docs won't move us closer to publishing.
  
  No, but if the project as a whole wants to be published, they/you'll have to 
work on it. A middle step would be to add kexi to the older scripts, but I 
don't know how. With the current scripts, it's seems not to be possible to add 
Kexi in Calligra's module in the current state of the scripts.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: ochurlaud
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[ochurlaud (Olivier Churlaud)]

ochurlaud added a comment.


  The things KApiDox deals with (what is on the front page) is only public 
libraries.
  
  What is not on the front page is done by other scripts that I don't take care 
of, so they might do anything.
  
  We spoke about enabling the private libs in KApiDox. It's feasible, but 
lesser priority. At the end, it should not land on api.kde.org which is 
targeting our developer users.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: ochurlaud
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[ochurlaud (Olivier Churlaud)]

ochurlaud added a comment.


  HI,
  
  It's not a mix. api.kde.org is for *public*api.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: ochurlaud
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  In https://phabricator.kde.org/T3755#55367, @kossebau wrote:
  
  > In https://phabricator.kde.org/T3755#55355, @staniek wrote:
  >
  > > > there is not much content right now on the kexi pages
  > >
  > > Right if you mean 'special pages' with prose. But there's plenty of 
doxygen API docs in the context of classes and functions. Over 4000 lines with 
@ or \ tag.
  >
  >
  > I meant "kexi pages" = "generated html pages" :)
  >  Your comment leaves me unsure if it was understood how it comes that right 
now only those pages are created from the existing api dox comments?
  >  If not, please have another look at what I wrote about the "tree of nodes 
with Mainpage.dox files" and ping me on irc for resolving the missing details :)
  
  
  I just did not find a browseable way to find Kexi docs.  I've been looking at 
the Other apps. Thanks for finding the Kexi page.
  
  We rather all agree about difference between library public APIs and 
project's own APIs. Separating them would be nice, especially that api.kde.org 
is now a mix.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  > No idea about Kexi, does kexi itself install libs with a public API?
  
  Nope, everything in this category has been moved to KDb/KProperty/KReport.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[kossebau (Friedrich W. H. Kossebau)]

kossebau added a comment.


  In https://phabricator.kde.org/T3755#55355, @staniek wrote:
  
  > > there is not much content right now on the kexi pages
  >
  > Right if you mean 'special pages' with prose. But there's plenty of doxygen 
API docs in the context of classes and functions. Over 4000 lines with @ or \ 
tag.
  
  
  I meant "kexi pages" = "generated html pages" :)
  Your comment leaves me unsure if it was understood how it comes that right 
now only those pages are created from the existing api dox comments?
  If not, please have another look at what I wrote about the "tree of nodes 
with Mainpage.dox files" and ping me on irc for resolving the missing details :)

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: kossebau
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[Jarosław Staniek]

staniek added a comment.


  > there is not much content right now on the kexi pages
  
  Right if you mean 'special pages' with prose. But there's plenty of doxygen 
API docs in the context of classes and functions.

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: staniek
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez

[Maniphest] [Commented On] T3755: Kexi API docs missing in the calligra section

[kossebau (Friedrich W. H. Kossebau)]

kossebau added a comment.


  For one, Kexi is currently covered by api.kde.org, just not explicitely 
listed on https://api.kde.org/other.php (similar to krita).
  @ochurlaud  Do you have access to that page and could add Kexi & Krita there?
  
  Kexi: https://api.kde.org/bundled-apps-api/kexi-apidocs/
  Krita: https://api.kde.org/bundled-apps-api/krita-apidocs/
  
  Now, there is not much content right now on the kexi pages. That is, because 
AFAIK those api dox pages are still generated by the old kdelibs doxygen 
scripts. Which organize things by the Mainpage.dox files they find in the repo. 
And do that in a way, that if they find a Mainpage.dox file in a folder, they 
will ignore content in any sibling folders below the next Mainpage.dox file at 
a higher level, unless there is a Mainpage.dox file in the sibling as well, 
which then would span a group of api dox for that section (image a tree of with 
Mainpage.dox files as nodes, and for the leaf nodes there is a separate api dox 
 section generated for any code in the folder starting at that leaf 
Mainpage.dox).
  So the file src/widget/undo/Mainpage.dox is masking any other dirs with code 
right now, resulting in the content visible on the linked pages.
  A fix would be to remove widget/undo/Mainpage.dox. That should result in 
apidox coverage for everything in src/ again (and that is not in EXCLUDE in 
src/Mainpage.dox).
  If you would like grouping per subfolder of src, add Mainpage.dox files into 
each of those direct subfolders, as new leafs to the Mainpage.dox tree :)
  
  All this is for complete API dox of the complete sources code, targetted at 
contributors. Which is a separate purpose to what the current redesign of 
api.kde.org targets on, which is documenting the public API of KDE products, so 
targetting 3rd-party developers of libraries with published API (which of 
course can also be KDE 3rd-parties, when using other KDE products in own 
projects).
  Where to put the "old style" content of api.kde.org (so anything e.g. at 
https://api.kde.org/other.php but also https://api.kde.org/history4.php), so 
the documentation targettted at project contributors, that is still open to 
discussion.
  
  For the libs in the "calligra" repo since the port there is no published API 
yet again, noone has looked into making the installed headers usable (and thus 
they are not even installed ATM). So no use to be on "new" api.kde.org right 
now.
  
  No idea about Kexi, does kexi itself install libs with a public API?

TASK DETAIL
  https://phabricator.kde.org/T3755

EMAIL PREFERENCES
  https://phabricator.kde.org/settings/panel/emailpreferences/

To: kossebau
Cc: kossebau, Calligra-Devel-list, bcooksley, ochurlaud, sysadmin, staniek, 
blazquez