phpcsstandards / phpcsstandards.github.io Goto Github PK

One of the ideas I'm playing with for the website is as follows (outline, details to be determined at a later point):

• Create a PHPCS Generator class which can generate Jekyll "Collection" format output based on the available XML documentation for sniffs.
• Create Jekyll templates to:
  • Display all available documentation of a standard as a webpage, including a list of the sniff in a standard which don't have documentation (yet).
  • Display the documentation of all sniffs which contain a certain keyword provided via a "search for a sniff" interface.
• Have a GH action via cron which will automatically update the Collections whenever any of the supported standards libraries tag a new release and commit the updated Collections file(s).

Constraints:

• PHPCS currently supports an XML format for the sniff documentation.
  This may very well change in the future.
  If and when, the Generator would need to change as well or rather: be able to take both the old and the new format into account to allow for standards which still use the old format.
• The current XML format is not documented, i.e. there is no XSD file available, so not all available files may parse correctly.
• The current XML format does not allow to structurally document which public properties can be set/changed in a sniff via a custom ruleset.

Future ideas:

• Add a tool, possibly to DevTools, possibly based on phpDocumentor, to be able to generate markdown documentation output based on the file/class docblocks of sniffs and the public properties which can be used in the Readme or another documentation file for a standard.
  An extension to that tool could then possibly extract that information in Collection format for it to be used here as well.
  This is intended to allow for standards which do not have XML documentation of the sniffs available.

Related: squizlabs/PHP_CodeSniffer#1752