search

demos-europe / edt

Enables your PHP application to expose its entities as REST resources using the feature rich JSON:API specification as API. How and to whom your entities are exposed is highly customizable while minimizing boilerplate code.
MIT License
2 stars 1 forks source link

Set up documentation building properly #135

Open dresslerdemos opened 4 months ago

dresslerdemos commented 4 months ago

A properly generated class documentation should be available somewhere, be it inside the docs folder, github pages, a github wiki or elsewhere.

After phpdocumentor was correctly installed (i.e. not using composer), the following commands can function as a starting point for experimentation. To make them more approachable, they could be added to the scripts section in composer.json.

        "gen-type-hierarchy": "php phpDocumentor.phar run -d \"packages/access-definitions/src/Wrapping/Contracts/Types\" -d \"packages/jsonapi/src/ResourceTypes\" -t docs2 --setting=graphs.enabled=true",
        "gen-docs": "php phpDocumentor.phar run -d \"packages/*/src/\" -t docs2"

It was not decided yet, if the generated class documentation should be put together with HTML documentation generated from the asciidoc files, or if those should reside elsewhere (or can simply be left as adoc files to be rendered by Github when opened).

Also note that asciidoctor supports automatically generating images from uxf (UMLet) files, which may need to be done manually or via custom workflow when relying on Github only.

dresslerdemos commented 3 months ago

https://github.com/gollum/gollum seems worth to be evaluated.