doctrine/rst-parser should be replaced with phpdocumentor/guides

[stof]

Doctrine itself does not use the doctrine/rst-parser package anymore, in favor of phpdocumentor/guides which is actively maintained by the phpdocumentor team, much more spec compliant and more extensible. The Doctrine team plans to abandon the doctrine/rst-parser package (focusing the team resource on maintaining the projects that are in the scope of Doctrine: persistence-related things).

The Symfony docs-builder should migrate to the new package, and will probably be able to remove lots of code added for workarounds of parser issues.

[wouterj]

While preparing for the stable release of phpDocumentor/guides, and with the help of typo3, we've already made huge steps into making this work: https://github.com/wouterj/symfony-docs-guides We need to revive that repository, integrate it with symfony.com and do lots of regression testing. I was already planning on quickly discussing this at symfonycon with Fabien, Javier and Jaap.

When Doctrine migrated their docs to phpDocumentor, I had a chat with Gregoire about this. We didn't expect Doctrine to want to maintain the package any longer and suggested to move its code into this repository as long as symfony.com isn't transitioned yet. But given the low maintenance (there is no change in the past 2 years basically), Gregoire and me decided to keep it in Doctrine for that moment.

So if the only thing blocking Doctrine from abandoning the package is us, let's move the code into this repository.

[stof]

So if the only thing blocking Doctrine from abandoning the package is us, let's move the code into this repository.

Given the low maintenance on doctrine/rst-parser (where we basically don't fix any spec incompatibility anymore on the Doctrine side), there is not an urgent need to abandon the package. The package is currently maintained more or less on a basis of fixing security issues only (and maybe fixing PHP deprecations, if contributed by someone).

As part of the Doctrine Core Team hackathon, I made community outreach to each open-source package depending on doctrine/rst-parser to try pushing them to replace their dependency.
The current plan is to actually abandon the package once symfony-tools/docs-builder is migrated (the text of the issues I opened in the symfony-tools organization is different from the text used in other packages due to that). But I still wanted to have a public issue referencing the fact that this package should be migrated at some point.
No need to move the code in the repo IMO.

While preparing for the stable release of phpDocumentor/guides, and with the help of typo3, we've already made huge steps into making this work: https://github.com/wouterj/symfony-docs-guides We need to revive that repository, integrate it with symfony.com and do lots of regression testing. I was already planning on quickly discussing this at symfonycon with Fabien, Javier and Jaap.

Note that given the dependency on the docs-builder in the code-block-checker package, it might maybe be easier to refactor docs-builder to use the phpDocumentor/guides library than to migrate the whole docs building process to the guides CLI.
It might also make it easier to integrate it in the symfony.com website (the public API of DocBuilder and BuildConfig does not leak anything about doctrine/rst-parser, so it depends whether the website integration relies on that public API or on the lower-level API configuring the rst-parser manually, as done in code-block-checker)