Where is the API Documentation?

1

I can not find anymore the API documentation on the Grav Learn website https://learn.getgrav.org/api

Does anyone know where to find it or recover somewhere?

Thanks

2

Was it ever there? I didn’t even know Grav had some API by default :eyes:

3

Yep. And it’s still linked by other pages too. ex: Theme Variables | Grav Documentation

1 Like
4

Oh, OK.. It’s this one

I never considered this as an API per se :man_shrugging:
Would have to ask Andy on Discord or on Github maybe why exactly he did remove the API page right on Christmas eve :sweat_smile:

Edit: I asked him on Discord myself. Weird decision TBH :slight_smile:

5

Here’s an answer directly from Andy:

yah removed it.. it was very out of date, i did try another API generator but just made thousands of very small pages that caused more trouble than it was worth

to be hoenst its not that useful.. easier to just use the source code and a good IDE

i never used myself.. not once.. if i want to find some method signature i just search and read the code

with AI now, it’s even simpler, just ask it :slight_smile:

6

Hm… That’s a pity because I used it quite often. I find a search in a single api doc page way easier then searching code…

When answering a question, adding a link to a function in the docs is also easier then providing a code snippet with the function’s signature.

1 Like
7

I fully agree.

And I try to don’t use AI

1 Like
8

@Karmalakas, Would you mind asking Andy to restore the API pages in the docs?

  • Not everyone lives inside code like Andy does
  • Not everyone uses AI. I find it a burden and have to undo its proposed code all the time.
  • If Andy is not willing, replacing the API doc page with a notification/explanation of its removal would be a tad more community minded…

Off topic: The new theme used for the docs does not add clarity imho, especially the topic tree.

1 Like
9

i agree with pamtbaau,

and what i guess is andy did that because only he works for that field?

if that is right, maybe he or someone should open a topic here to find who wants to maintain that work
and if more than one found we can use poll to select one of them.

actually we can start doing this with selecting if we want to have api page like we used to with using poll

actually we can start with selecting if we want to use poll to decide things with using poll :slight_smile:

we can even select who can use poll for those like a tag system here. or start with some members only like core members. im fine with that too.

but i want a poll :slight_smile: because i dont like one guy decides all alone even if it is me or my dad or my grand father

10

Agree with all of the anti-removal posts here and especially disappointed how this wasn’t announced (at least on this official channel). I also used it extensively although I did notice that it sometimes didn’t agree with the codebase and now I know why.

Just floating the idea that someone could self-host it, either freshly generated or based on a previous version of the docs repo. I’m prepared to host it but don’t want to promise something I may not get around to delivering on any time soon. Certainly I think it’s a careless suggestion to be wasting resources generating this (AI or not) over and over again the same :deciduous_tree:

11

Andy suggested to maybe try and generate it locally

you can theoretecially still run the script locally on your machine.. make sure you have installed all teh dev libraries with composer install, and then run composer api. It’s currently configured to install into user/pages/17/14.api as that is the grav learn location..

i have trouble running it myself as i already had to fork it to grav (getgrav/markdowndocs) years ago because it was no longer maintained. Now it has problems with later versions of PHP, and i’ve not bothered to fix it.

1 Like
12

I finally got this to work. I found a tool which can use Github Actions to build PHP documentation from a repo, so used it as an opportunity to learn about GH Actions. Not sure I learned much TBH but I got there. Please consider this temporary:

I will write up more about my workflow when I have a bit more time.

I think that eventually someone should package this workflow into a compelling PR on the main Grav repo, so that it triggers whenever code is pushed to its master branch. I don’t know how to keep my fork automatically synced with upstream and don’t want the ongoing task of doing it manually.

Sorry for my brevity, hope this is useful for the moment.

[Edit: main → master]

2 Likes
13

@hughbris, Seems we both have been playing around with phpDocumentor.

The default output of phpDocumentor is not to my liking, I’ve therefor created a rough template that generates a default.md page mimicking the known format of the former API docs.

If you’re interested, I’ve dropped the template inside repo GitHub - pamtbaau/grav-api-docs.

I haven’t looked a GH Actions though. Since you seem to know all about it now, maybe you can find a way.

My hope is that @rhuk, will be able to use this proof-of-concept and restore the API docs.

Here are a few screenshots of the resulting API page:

image
image1424Ă—363 20.6 KB

image
image1410Ă—502 45.8 KB

1 Like
14

I really don’t know much about it. That was one of the points I tried to make in my hurried write-up. It’s trial and error. You’ll see my commit history is full of frustrated passive-aggressive let’s-see-if-this-works-style comments.

I do know that the GH Action spins up a Docker container to run phpDocumentor. Most of my version is based off this issue and PR comment. My level of comprehension of most steps in the workflow is sadly still minimal. I don’t find the action configuration idiom very intuitive at all.

Me neither, and I was just about to play with the configuration options. It looks like we need to create a phpdoc.xml file with <setting> elements but it’s unclear where that should go in the GH Actions/container context, so I guess I’ll figure that out by crapshooting as well :face_with_raised_eyebrow: It’s ironic that phpDocumentor has such vague documentation itself.

If you share your configuration options (in whatever syntax), I will integrate them into the GH Action config when I figure out how to reference it. Happy for you to do that. I had only planned to change the template colour, title, and add some menu items.

I thought I might try generating a diagram after that, but that is getting ahead.

Hopefully. Someone other than me will need to package up a PR that just works, and make the case.

15

@hughbris,

Since you seem to know all about it now

I read your frustration, my comment was just to tease you a bit… :wink:

1 Like