Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Auto-generate sniff documentation of various standards to display online #1

Open
jrfnl opened this issue Jan 5, 2021 · 0 comments
Open

Comments

@jrfnl
Copy link
Member

jrfnl commented Jan 5, 2021

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant