squizlabs
Updating the documentation (demo included)
One of the main issues for anyone to start using PHPCS (myself included) is the lack of documentation. When I started using a couple of years it was a very difficult task to implement it. I am using it with VSCode so I had to google for many hours/days to get it finally working.
Documentation is available for many parts of the script, but it is:
- Not comprehensive: many areas require further clarification/updating like sniffs.
- Not organized: it is hard for a begginer to find where/how to start using it.
I realize it is something have been discussed previously and the direction chosen by @gsherwood is to make the docs external and not use xml.
Since I extensively use ESLint rules in my projects, I thought something similar might be achievable for PHPCS.
So, using various sources (wiki, xml docs, phpdoc in sniffs) I built this documentation using vitepress. It is not complete and needs more work to make it production ready but I think it is a start.
Some examples from the demo:
- List of Generic rules
- Installation page
- Coding Standard Tutorial
- Single rule details with (valid/invalid) examples
- Single rule without examples
- Single rule with properties and usage
Using vitepress has many advantages over using GitHub wiki, for example:
- I think the UI (and in turn the UX) is much easier to navigate.
- Link to GitHub to edit a particular page.
- Responsive.
- Dark theme.
Like many developers of open source, the maintainers of this project is busy with work/life/personal stuff ... etc. I think that the documentation will make it easier to attract developers who otherwise are turned off by spending hours aimlessly trying to figure out how to run a simple command.
The documentation repo is available here: https://github.com/kalimah-apps/phpcs_docs
