Join GitHub today
GitHub is home to over 28 million developers working together to host and review code, manage projects, and build software together.Sign up
Online API browser #53
Hello fellow @hoaproject/hoackers and users!
I would like to have a nice online API browser for our libraries. Ready?
Is it a solution we could maintain? Do we have better alternatives? What do you expect from an API browser?
Solutions for PHP
Personally, I don't like any of them.
Solutions in other languages
Build our own?
I really like the approach of
For each class, we have a long description. Then we have modules (namepaces in PHP) with a description.
But the browsing experience is great.
All API documentation generator I tried in PHP didn't catch me. In other languages, like Rust or Elm, we have very nice ideas. We must get inspired from them.
I am not afraid of building a new tool. I personally thing this is the direction to take.
referenced this issue
Feb 27, 2017
It looks like you love parsing the docblocks. I have came across lithium which does something similar. Not a standalone one. But it has some plugin when installed your whole framework docs all will be shown.
The plugin is : https://github.com/UnionOfRAD/li3_docs
The documentation written in class is as
once it is rendered you will see something as : http://li3.me/docs/api/lithium/1.1.x/lithium/action/Controller .
I guess this is what you are looking for. I looked at Kitab, but as it has less information how the docs should be written etc I am not very sure also.
A namespace page
On the left, we have the navigation, which is “all the sibling data”. You must understand it as “namespaces in the same level”.
On the center, we see one namespace in details, with all entities it contains: Classes, interfaces, traits, and functions.
A class page
The class page has been enhanced with more data. Markdown is converted into HTML for the doc comment attached to methods. We have syntax highlighting. Markdown to HTML does not auto-convert entity names (like class names) into links yet. This is expected in a close future.
The class documentation will be placed just before the “Methods” heading.
It is kind of slow when we have more than 600 files to analyse, but I am working on a cache (the slow part is to build the search index, we can cache it, but I don't know how to orchestrate that).
Anyway, it works great
Here is the
Great news! The search data are now compiled ahead-of-time. What does it mean? 3 files are now computed:
Having the index and the metadata separated really helps to reduce the size of the index (by a factor of 65% with my recent tests).
Why doing this? To reduce the initialisation of the search on the client-side. Now, initialisation of the search drops from 17s to… 369ms
I am very happy with these results. Not to say that
The size of the search module
We have a complete reactive UI with an advanced search for 600+ files for 400Kb. This is still less than Ember or Angular alone —just the framework, not the app— (source).
Interface support for the HTML target are better.
@Grummfy Sure. This is always the case. Choose another target, and here you go, https://github.com/Hywan/Kitab/blob/ad3a72231c9e997b8be065dfab59cd724fc08e2a/src/Compiler/Compiler.php#L91.
Note about namespace description. Any classes, interfaces, traits, or functions can have a block comment attached to it, in a single place. However, for namespaces, we have many locations where to write the documentation. Because this is not obvious and undeterministic, I have decided to look for a
About links to source, it is attached to each entities (classes, interfaces, traits, functions, and even methods).
Here is an online example https://hywan.github.io/Kitab/kitab/index.html of https://github.com/Hywan/Kitab. On this documentation homepage, you can see the
Please, fill bugs or discuss here :-). Feedbacks are really appreciated!
Well in this case, I would expect that "Type" or "File" would be clickable because thier are class that exist inside the documentation. For that's the only expected things that I see.
As extra information/plugins, I really enjoy to have stuff like phpxref to cross check the usage. But not directly accessible.
Bug in namespace links is now fixed, https://hywan.github.io/Kitab/kitab/index.html.
After that, we will be good to try a 1.0 beta, and deploy it on Hoa.
And here we go, since Hywan/Kitab@1950f62, all qualified names are clickable. I still have an issue with
I find interesting how to document things without saying: “Return bla bla” or “Get bla bla”, because the name of the function or method must be self-explanatory! So taking the example of
Actually, this is the only explanation we expect at this step. We know the method is called
This is interesting to rethink how we write documentation.
It renders on Github too! On Github: https://github.com/Hywan/Kitab/tree/master/src/Compiler, on Kitab: https://hywan.github.io/Kitab/kitab/compiler/index.html.