Description
Today I spent some good hours researching on how we could manage this new documentation to the Driver, so here's some ideas.
Goal
The idea is to build something like Laravel Docs or even Sphinx ScyllaDB, where we can have some possibilities to build on top of this documentation AND easily parse and generate the .stubs files.
Research
My first attempt was with phpdocumentor and I managed to achieve a good result with it, however I faced a problem which is basically: it's running a very old Bootstrap version.
Besides that, doesn't look that it would be a good thing to maintain (even a fork) after digging into the source to understand about the project since they don't have a practical documentation either.
Then I tested the Doctum Docs Generator which the focus is to solve the .stubs problem. It works flawlessly and is being used by all biggest PHP frameworks for ages, so we can stick with that.
Then I tested Sphinx, another doc using Astro and finally Docusaurus which I particularly liked a lot and IMHO solves the problem of the "human documentation" side.
Plan
To make work, my goal will be merge 2 documentations into one, where we will have:
GET - / -> Docusaurus generated docs
GET - /api -> Doctum API docs
With this mashup, we gonna have an elegant and functional documentation for both sides.
Requirements
Here's the task list to make it a thing and since we can point each folder the Doctum will be searching, it's not a big deal to keep the .stubs inside the src/ folder. So:
- Generate all file stubs inside
src/folder after a commit/release/change in the API - Write the Docusaurus "Human Docs" for newcomers
- Mixed GH Actions on Docusaurus and Doctum to a single project.
Activity