[doxygen] auto doxygen test

[AlwinEsch]

Description

This brings an idea of mine to be able to use the doxygen documentation of both types (Kodi itself and addons).

This is currently not correct and needs your ideas and instructions as best.

Also with the actions-gh-pages which it would upload to github website is just an idea, since xbmc doesn't use it yet and can also be loaded to other places. Stupid (and also good) about it is that I couldn't test it on my https://alwinesch.github.io/ because my Kodi is only a fork, see e.g. here his build log https://github.com/AlwinEsch/kodi/runs/4195004521?check_suite_focus=true#step:7:33.

Background would be something like this:

In addition, CodeDocs.xyz does not work with externally stored files in Doxygen, see note here #20432 (comment).

What would you think of something like that and what would be the best way to upload it somewhere?

Motivation and context

How has this been tested?

What is the effect on users?

Screenshots (if appropriate):

Types of change

• Bug fix (non-breaking change which fixes an issue)
• Clean up (non-breaking change which removes non-working, unmaintained functionality)
• Improvement (non-breaking change which improves existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that will cause existing functionality to change)
• Cosmetic change (non-breaking change that doesn't touch code)
• None of the above (please explain below)

Checklist:

• My code follows the Code Guidelines of this project
• My change requires a change to the documentation, either Doxygen or wiki
• I have updated the documentation accordingly
• I have read the Contributing document
• I have added tests to cover my change
• All new and existing tests passed

[AlwinEsch]

The branches: [ doc-upload ] above should be in Kodi branches: [ master ] (currently set to my one for test).
And if: github.repository == 'AlwinEsch/kodi' should be then if: github.repository == 'xbmc/xbmc

As working upload by script I has on begin worked with here https://github.com/AlwinEsch/kodi/tree/gh-pages (where works on a forked repo).

[ProfYaffle]

I'm not being rude by ignoring the review request... I've just been puzzled by what's needed here!

Are you basically suggesting that, alongside the existing Doxygen stuff, we have something similar for addons? Maybe move the skin stuff there, maybe API information, that sort of thing - so we have "working in core Kodi" separate from "building around the edges and talking to Kodi"? If so, I can't see why that would be a problem: documentation that describes how to structure, build and package addons, as well as the methods/calls needed for Python, binary addons, whatever.

Or is it more that people should build better documentation into their addons, and we then host/link to the Doxygen-built documentation for the addons themselves ("this addon does this like this, using these methods and dependencies", and so on)? I genuinely don't have an opinion on that, as I don't know how complex addons are or how much people fork them, reuse code, build new ones, and so on. It might certainly help if popular addons (and skins?) get abandoned, in that someone else could perhaps pick them up and bring them back to life on e.g. an API change.

I may be missing something entirely, however...

[AlwinEsch]

Are you basically suggesting that, alongside the existing Doxygen stuff, we have something similar for addons?

Yes exact. The associated doxygen part has been around for years, but it has never been used publicly.

My main concern is to have it independently available for the addons, because in Kodi's complete Doxygen it is very confusing and for inexperienced (and even for experienced) it is very opaque because Kodi's complete descriptions are there.

Look here "https://codedocs.xyz/xbmc/xbmc/" and think about how an inexperienced person would find the correct python / skin related description. Since complete Kodi is listed in it, it becomes rather difficult.

Both doxygen projects (kodi-dev-kit and Kodi itself) use the same descriptions, only the kodi-dev-kit is limited to addon-related parts. Regarding the skin, it may be that parts are still missing there, but also difficult to find out easily in Kodi.

You can compare them of Kodi with https://alwinesch.github.io/index.html.

[AlwinEsch]

In addition, some Doxygen parts will have to be fixed and improved in the near future. Again many errors crept in with skin and Python API updates.

[ProfYaffle]

I did look at the codedocs stuff previously - and, you're right, it was virtually impossible to see anything specific to addons.

There is a Skin Development section, which at least explains the controls, but the Addon functions (etc.) are hidden alongside all the other built-ins. It's certainly not obvious where to start if this is the only documentation you have - but there is also the pretty comprehensive addon wiki, however, plus the skin one, so they probably all need to be considered together to avoid duplication.

There's also some minor Python API stuff in codedocs, but that only really seems to document changes in this API release - there's no obvious link from these to a baseline list of calls (they're probably scattered in those lists of built-ins). Again, I suspect much of the "how you use Python for addons in Kodi" stuff is in the wiki already.

[enen92]

IMHO we should also take this opportunity to completely drop codedocs. It is using (or was using) a really old version of doxygen and it's hard to keep up. Nowadays with github actions and github pages we can certainly make the pipeline generate the new page and host it in github pages on every merge. Furthermore it'll allow us to theme doxygen if we decide to.

At the moment our docs on codedocs are completely broken:

v20 changelog for python (code docs): https://codedocs.xyz/xbmc/xbmc/python_v20.html
v20 changelog for python (alwinus page): https://alwinesch.github.io/python_v20.html

[AlwinEsch]

but there is also the pretty comprehensive addon wiki, however, plus the skin one, so they probably all need to be considered together to avoid duplication.

In many contexts this is really great, but keeping it always correct and up to date in relation to API changes makes it more difficult, because something could easily get lost. Therefore, in this regard, Doxygen found it pretty good, as the respective developer can (and should) always insert the descriptions so that it is up to date.

You only have to be careful in Doxygen that errors do not occur when changes are made (here last fix #20432 (comment))

[AlwinEsch]

Here need to change to ' xbmc/xbmc'.

[AlwinEsch]

It would require an empty branch in Kodi which would have to be introduced with:

git switch --orphan gh-pages
git commit --allow-empty -m "Initial commit on orphan branch"
git push -u origin gh-pages

If OK for you, could I already create such a branch in xbmc?
Or can I think of another name? The "gh-pages" is the default of the Action plugin and would be OK for me.

Here the generated docs about:

• https://alwinesch.github.io/test-xbmc/kodi-dev-kit/
• https://alwinesch.github.io/test-xbmc/kodi-base/

The test-xbmc comes from my temporary added repo with name test-xbmc, should be by Kodi then https://xbmc.github.io/xbmc/.

[enen92]

@AlwinEsch is branching supported with this new implementation? I mean, it'd be great if we could push doc pages according to branch (Matrix, master (nexus currently), etc)

[AlwinEsch]

@AlwinEsch is branching supported with this new implementation? I mean, it'd be great if we could push doc pages according to branch (Matrix, master (nexus currently), etc)

Yes, does work and updated it, need then only to have the matching documentation-creation.yml inside his branch.

Here the created ones:

• https://alwinesch.github.io/test-xbmc/master/kodi-dev-kit/index.html
• https://alwinesch.github.io/test-xbmc/master/kodi-base/index.html
• https://alwinesch.github.io/test-xbmc/Matrix/kodi-dev-kit/index.html
• https://alwinesch.github.io/test-xbmc/Matrix/kodi-base/index.html
• https://alwinesch.github.io/test-xbmc/Leia/kodi-dev-kit/index.html
• https://alwinesch.github.io/test-xbmc/Leia/kodi-base/index.html

[enen92]

Couple of suggestions:

• maybe better to create xbmc/docs within the org and use external_repository to avoid polluting this one with doc branches. See https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-deploy-to-external-repository-external_repository

• do we want to trust external actions and use them from repos out of the org/foundation control? Since they can access secrets from the repo wouldn't it be better to just fork and freeze on a specific git sha?

Thanks much for this, hopefully it can be merged soon along with the removal of broken codedocs.xyz . We might need to point docs.kodi.tv to the new address in cloudflare once this is finished

[AlwinEsch]

Related to:

maybe better to create xbmc/docs within the org and use external_repository to avoid polluting this one with doc branches. See https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-deploy-to-external-repository-external_repository

I updated it and is now uploading to another repo https://github.com/AlwinEsch/docs.kodi.tv.
To have only one upload I added two sed calls and to edit the target dirs, so the upload have only one dir.

E.g. here https://alwinesch.github.io/docs.kodi.tv/master/kodi-dev-kit/ now available.

About:

do we want to trust external actions and use them from repos out of the org/foundation control? Since they can access secrets from the repo wouldn't it be better to just fork and freeze on a specific git sha?

I think for security reasons, think it would be best in "github", since all accesses only take place within and not to our mirrors / servers. In addition, we then do not need to have any disk space available 😺.

[AlwinEsch]

The code in yml is now set to the right names on Kodi. Has used as repo name the docs.kodi.tv, other ideas about, thought to make like in kodi.tv becomes used?

[enen92]

The code in yml is now set to the right names on Kodi. Has used as repo name the docs.kodi.tv, other ideas about, thought to make like in kodi.tv becomes used?

I mean http://docs.kodi.tv currently redirects to our codedocs.xyz. When this is finished we need to change it in cloudflare to point to the new gh pages site. Kib handled this at the time, I guess wspinex might be able to do it when this is finished.

[enen92]

I think for security reasons, think it would be best in "github", since all accesses only take place within and not to our mirrors / servers. In addition, we then do not need to have any disk space available 😺.

Yeah, I don't think running this in Jenkins is a good idea. I was just wondering if we shouldn't fork the actions and run then from the org instead of linking external repos out of our control. I.e., instead of uses: peaceiris/actions-gh-pages@v3 run it as xbmc/actions-gh-pages@v3.
I am not sure if this is a concern though, not sure if the extension can read the secret (I assume it does). Just food for thought.

[AlwinEsch]

I am not sure if this is a concern though, not sure if the extension can read the secret (I assume it does). Just food for thought.

Yes, its code must be readable for him, otherwise it would not be able to upload to the repo.
It's always a tricky situation with things like that, if we had a fork of it, something could not come in unexpectedly at once.

The only good thing is that it would only have access to https://github.com/xbmc/docs.kodi.tv and nothing else and there you could see what is coming in commit history or branches. Which makes it really better to load it into another repo so that there is no write access in xbmc.

But we have to trust it a little and since it is used a lot and is active in the github marketplace 🤔😅😏 .

[enen92]

Right, that's a good point. If the secret is granted in a way that write access is only available to the docs repo it should be safe

[AlwinEsch]

If we do for Kodi then the following steps are needed:

1. Create a empty repo named docs.kodi.tv in https://github.com/xbmc
2. On https://github.com/xbmc/xbmc/settings/secrets/actions a add of private key ACTIONS_DEPLOY_KEY created by ssh-keygen to Repository secrets
   • See docs on https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-create-ssh-deploy-key
3. On https://github.com/xbmc/docs.kodi.tv/settings/keys the add of second Public key of ACTIONS_DEPLOY_KEY created by ssh-keygen before
4. This request then in (maybe changed to another name on key, see note below)
5. Then have his works upload access to it and time to start first build and upload
   • After them the main branch becomes present
6. Inside https://github.com/xbmc/docs.kodi.tv/settings/pages can then the publicated branch set to use as https

Also another name instead ACTIONS_DEPLOY_KEY can be used, maybe to have more clear as DOC_ACTIONS_DEPLOY_KEY?

[enen92]

I'd drop the codedocs integration in another commit but it's out of scope of the PR. Thanks much for working on this, our docs are currently completely broken.

I guess our friend @Darren-Hill can probably help setting up the new repository in the XBMC org for gh pages and setting the write secret for that new repo. Let's hope he is on a Christmas mood :)

[Darren-Hill]

@enen92 - whilst I may have the privs and access for that, I'm not sure I have the GitHub skills to do so.

I'll try and follow the steps listed above and see how it goes, but don't blame me if chaos ensues...

[Darren-Hill]

@enen92 @AlwinEsch - I've made the new repo and added you both as admins of it.

Can you handle the keys stuff and onwards as that's getting somewhat beyond my comfort zone to set up?

[enen92]

looks like we might need to fork the actions, relax settings or add them to the whitelist