search

UniFormal / MMT

The MMT Language and System
https://uniformal.github.io/
Other
68 stars 22 forks source link

"Known subclasses" doesn't list any in API documentation #552

Open ComFreek opened 3 years ago

ComFreek commented 3 years ago

e.g. see https://uniformal.github.io/apidoc/info/kwarc/mmt/api/ontology/Unary.html. Known subclasses is just empty there.

@tkw1536 Do you know what's wrong there?

tkw1536 commented 3 years ago

As of 657345e877ea4add53eb3d882360362e0620d271 the api documentation isn't updated anymore. After a conversation in Mattermost the result was there wasn't enough usage to warrant migrating it from Travis to GitHub pages.

ComFreek commented 3 years ago

That's unfortunate. I used it extensively to get a good picture of the structuring of the API and now tried to use it again. How about other people wanting to use the MMT API? There are few, but they might as well think: if a system that I am considering using does not even have public API documentation, I better not start using it. (And honestly, I do the same for other projects.)

Do we want to keep the outdated API docs online?

ComFreek commented 3 years ago

Is generating the API docs using GitHub actions (just for the master branch) really that much work? I could look into it sometime -- if we can agree to revive it if I managed to.

tkw1536 commented 3 years ago

If you manage to, sure. My take on it: Generation of the apidoc is simple, authenticating and pushing to a separate repository is hard.

ComFreek commented 3 years ago

@tkw1536 Could you elaborate on why "pushing to a separate repository is hard"?

I've googled a bit. As per GitHub's docs on encrypted secrets, we should ideally use a deploy key: a signature key pair whose public pair should be registered with the repo (on its settings page) and whose private key should be provided as an encrypted secret to GitHub actions.

I also found https://github.com/marketplace/actions/webfactory-ssh-agent, which seems to make using the private key boxed in the encrypted secret for git push extremely easy.

Any objections?

tkw1536 commented 3 years ago

No objections on doing exactly that. It was more annoying to do than hard.

ComFreek commented 3 years ago

Nice. Then somebody with permissions would need to

  1. create a key pair
  2. upload the public key on this repo's settings page
  3. and upload the private key on this repo's GH actions secrets page.

I lack the permissions to do that. But afterwards I can do the build integration.