Update Instructions for Building RST Documentation

[robfrawley]

Problem Details

The symfony/symfony-docs project has changed their RST documentation build procedure from a Python and Sphinx compilation process to a PHP application in symfony/symfony-docs#16068.

The new RST documentation build process relies on an internal (and not officially supported, but MIT licensed) PHP command-line app in the symfony-tools/docs-builder project, which internally utilizes the doctrine/rst-parser library for RST parsing.

Over the next week or two, I will be updating the Wiki instructions for this bundle to use the new symfony/symfony-docs RST documentation build procedure, and will further provide a pull request to address any changes needed within the project itself to facilitate the new RST compilation procedure.

If anyone has any feedback as to how our RST build instructions could otherwise be improved, or if anyone has any input as the primary goals of this report, please feel free to comment. Otherwise, I will provide updates here as I progress.

Template Questions

Preconditions / Steps to Reproduce

1. Follow the RST documentation compilation instructions from github.com/liip/LiipImagineBundle/wiki/Building-RST-Documentation.

Expected Result

1. The bundle RST documentation is compiled into HTML.

Actual Result

1. An large number of steps fail due to the instruction's reliance on symfony/symfony-docs files and build process.

[dbu]

thanks for bringing this up.

in other OS bundles i maintain, we have have a github action to build the documentation, including an .rst spellchecker (e.g. https://github.com/FriendsOfSymfony/FOSHttpCache/blob/master/.github/workflows/spellcheck.yml). this both is a "living documentation" on how to build the docs, as well as immediately reporting issues when the documentation is changed. if we could do the same here, that would be awesome.

if you find a good solution, the doc at https://symfony.com/doc/current/bundles/best_practices.html#documentation could be updated with it, and we should tell the maintainers of all bundles in https://symfony.com/bundles that they could use the same system. (i had a quick look at doctrine bundle and the maker bundle, they don't yet build documentation in the CI). we could ask around in the symfony slack, probably in the #documentation channel.

[robfrawley]

@dbu That sounds like an excellent solution. I'll check out the Github actions; thanks!

[dbu]

the github actions in the example i linked are using the python sphinx library (makes sense for that repo because that is what readthedocs is using). i think for the docs here using the symfony tool makes sense, to be as close to the actual thing as we can.

[robfrawley]

Ah; got it (and agree). I'll look to submit a PR addressing the following items then:

• Update the relevant GitHub actions YAML file to use the Symfony docs build procedure.
• Update/remove/add any relevant build-related files/assets to achieve the same.
• Update the Wiki to provide some basic OS-specific information (for setting up the required development environment to successfully build the docs on Linux, OSX, and Windows) and then link to the new GitHub actions YAML file for specific doc building instructions without repeating them in the Wiki

After everything above is ironed out, we can look into offering our updated doc building method to other Symfony bundles, as you had previously mentioned.