[Idea] Autodocument API changes on each Perpl release

[kasparsatke]

💡 Proposal for a new approach on the API documentation 💡

For a lot of reasons, I like that there is https://api.propelorm.org. One can (still!) find a lot of info there you don't find elsewhere without fighting through half the codebase. And it even has a mostly useful in-app search. And it's totally legit the way it was conceived - b/c one cannot explain all possibilities and use cases by hand in the normal documentation, but the API still needed to be documented somehow.

But there are also a lot of reasons why it just feels half-assed:

• It's in a subdomain we don't control & hence can become unreachable anytime - yes I am looking at you http://sandbox.propelorm.org!
• It's decoupled from the actual codebase, sitting in a manually created repo https://github.com/propelorm/api.propelorm.org
• Even if we were to fork and try to refresh it manually, the build process relies on the long abandoned package https://github.com/FriendsOfPHP/Sami which itself has quite a few dependencies that might become pitfalls after all these years
• It's current state reflects a snapshot of the API from over 11 years ago and I think that it is at least partly due to my two points above that it is so hopelessly outdated
• It does not really integrate with the rest of the documentation in terms of design, structure, scope
• It is cross-origin at the moment and would stay so until we would find a way to integrate it to https://perplorm.github.io

---

Therefore, I am proposing an alternative:

1. Integrating a new API documentation into the general user documentation
2. Making it available in three ways:
   • both on its own page (be it api, index, glossary page or whatever) and
   • directly from within the user documentation via a call from a documentation item:
     • let's say I have a code field somewhere in the docs addCondition() and want to know how that method works
     • I then hover or click on it and get a preview or modal of the API documentation of this method with a link to more stuff
   • additionally via a site-wide search
3. Updating this API documentation automatically on each release of https://github.com/perplorm/perpl with a cross-repo github action

For initial data generation, I imagine to go about it in a similiar way as the original API docs: taking the perpl repo getting all the stuff parsing methods and their docblocks, which we have quite some ;-)

For the ease of calling and manipulation I would than suggest to store this in JSON files or an SQLite file rather than having static html files like https://github.com/propelorm/api.propelorm.org does it.

But I am sure there will be edge cases all around - so I am thinking of an additional annotation method too to make adjustments by hand if neccesary.

For some parts of what I just said in the last paragraphs it might still feel a bit like reinventing the wheel. But the magic comes with the automatic updating (3) on release if this is possible with a github action. So we would have an always up-to-date index of all the namespaces, classes and methods and maybe even properties that are at hand in our codebase. And their location in the source files. Additionally, we could tag their availability in the different releases and indicate if they were added, moved, deprecated or deleted from one release to another.

Please let me know your thoughts about this idea!

[mringler]

I have never used api docs, to me, it doesn't offers more details than phpdoc in IDE or jumping to the declaration, but is more cumbersome to use.
There are probably GitHub Actions that build doc files from public methods, if you want to look into that and create a PR, I am happy to add it.

[kasparsatke]

For me, one thing it's about integration, convergence, UX.

While reading the documentation to learn something, switching media (e.g. to the IDE) might be an unnecessary interruption of focus that feels uncomfortable and slows down the thinking and learning process. In German, we call it "Medienbruch".

Secondly,

to me, it doesn't offers more details than phpdoc in IDE or jumping to the declaration, but is more cumbersome to use.

... is exactly one thing I also want to change for good!¹ With:

• custom annotations,
• version info
• tight integration into the documentation (e.g. by querying API info directly from a <code> field)
• potentially a dependency graph/tree (just came up with this idea while writing)
• ... and another secret use case I still have to wrap my head around before I say more about it

Thirdly I guess you personally know the code base in and out at least halfways by now. So for you, there is little incentive to read the documentation at all, in general. So I think I get the point for you & I hence guess you would not feel any "Medienbruch" I am mentioning with the documentation at all.

But I predict there are "plain users" which rely on the documentation mostly/only as they don't work on the source code of Perpl as you do.

There are probably GitHub Actions that build doc files from public methods, if you want to look into that and create a PR, I am happy to add it.

I think I know what I want to achieve with the potential Github action for now but I am sure I will need help on some specifics in the end. I would like to ask once I have more in my hands than just my concept and explanations I have now.

---

¹At least for people that rely on the documentation 😄