doc: Validate documentation rst with phpdocumentor

[GromNaN]

Q	A
Type	improvement
BC Break	no
Fixed issues	#2640

Summary

Use phpdocumentator cli to validate rst files.

[GromNaN]

WARNING: Content of .. sectionauthor:: name <email> must specify a name and can also specify an email

[GromNaN]

WARNING: Document "sidebar" isn't included in any toctree. Include it in a .. toctree:: directive or add :orphan: in the first line of the rst document {"rst-file":"sidebar.rst"} []

[jmikola]

I noted that the ORM's documentation workflow manually added :orphan: before validating. Is there a particular reason that approach was preferred there instead of modifying the RST directly as you've done here?

I don't have any objections to this, but I wonder if it'd be worth suggesting upstream to the ORM team.

[greg0ire]

orphan is not supported by doctrine/rst-parser, which we still use for generating our docs

This means that if you don't use the trick I used, you are going to end up with :orphan: being printed above the sidebar of your docs 😅

[GromNaN]

Thanks for the clarification, I've adopted your solution that adds :orphan: in the job.

[GromNaN]

WARNING: No replacement was found for variable |FQCN| {"rst-file":"reference/custom-mapping-types.rst"}

[jmikola]

I noted that the ORM's documentation workflow manually added :orphan: before validating. Is there a particular reason that approach was preferred there instead of modifying the RST directly as you've done here?

I don't have any objections to this, but I wonder if it'd be worth suggesting upstream to the ORM team.

[jmikola]

Noted that this was adapated from the ORM action.