search

FriendsOfSymfony / FOSRestBundle

This Bundle provides various tools to rapidly develop RESTful API's with Symfony
http://symfony.com/doc/master/bundles/FOSRestBundle/index.html
MIT License
2.79k stars 707 forks source link

Setup docs #2348

Closed goetas closed 2 years ago

goetas commented 2 years ago

https://fosrestbundle.readthedocs.io/en/docs/

W0rma commented 2 years ago

https://github.com/FriendsOfSymfony/FOSRestBundle/blob/3.x/Resources/doc/annotations-reference.rst#route is not parsed properly since it relies on the sensio.sphinx.configurationblock extension which is also used by symfony docs.

I'm not sure if it is worth installing the extension or if we should stop using this syntax.

Edit: Alternatively we could just use the ::tabs syntax like in https://github.com/readthedocs/readthedocs.org/blob/master/docs/config-file/v2.rst - I guess this should be sufficient for our needs.

I'm glad to rework the section in the docs as soon as this PR got merged.

goetas commented 2 years ago

@W0rma thanks for the review, i've added the support for the custom sensio extensions, could you please check it again?

W0rma commented 2 years ago

@W0rma thanks for the review, i've added the support for the custom sensio extensions, could you please check it again?

Thank you for trying this out!

The code blocks get at least rendered as unordered list. symfony-docs are using https://github.com/symfony-tools/docs-builder for rendering. However, this tool is internal.

Maybe we should just use the native ::tabs syntax like in https://github.com/readthedocs/readthedocs.org/blob/master/docs/config-file/v2.rst - IMO it should be sufficient for our needs.

goetas commented 2 years ago

Looks much nicer https://fosrestbundle.readthedocs.io/en/docs/annotations-reference.html

W0rma commented 2 years ago

Great - thank you for working on this!

I'm going to adjust https://github.com/FriendsOfSymfony/FOSRestBundle/pull/2326 after your PR got merged