|
| 1 | +Hi, thank you for your interest in contributing to the PHPCompatibility website! We look forward to working with you. |
| 2 | + |
| 3 | +Aside from a few specific pages, the documentation on the website is automatically generated from the source code of the [PHPCompatibility repository](https://github.com/PHPCompatibility/PHPCompatibility). |
| 4 | + |
| 5 | +The contents maintained in this repository are: |
| 6 | +- The pages in the "Using PHPCompatibility" section. |
| 7 | +- Site layout and structure. |
| 8 | +- CSS customizations. |
| 9 | + |
| 10 | +Pull requests to improve either of these are welcome. |
| 11 | + |
| 12 | +All the sniff and error code related content is auto-generated from a combination of: |
| 13 | +- The sniff class docblocks for each sniff in the [PHPCompatibility repo](https://github.com/PHPCompatibility/PHPCompatibility/PHPCompatibility/Sniffs) |
| 14 | +- The sniff specific additional documentation (if available) in the [PHPCompatibility repo](https://github.com/PHPCompatibility/PHPCompatibility/PHPCompatibility/Docs) |
| 15 | + |
| 16 | +Improvements to the sniff and error code related content are very welcome, but should be pulled to the [PHPCompatibility repository](https://github.com/PHPCompatibility/PHPCompatibility). |
| 17 | + |
| 18 | + |
| 19 | +## How the website is generated |
| 20 | + |
| 21 | +This website is a [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages) site using the [Jekyll Site Generator](https://jekyllrb.com/) with the [Liquid template language](https://shopify.github.io/liquid/) with some [Jekyll specific additions to Liquid](https://jekyllrb.com/docs/liquid/). |
| 22 | + |
| 23 | +The website uses the [jekyll-rtd-theme](https://jekyll-rtd-theme.rundocs.io/) using the [rundocs core](https://rundocs.io/) with some site-specific customizations. |
| 24 | + |
| 25 | +The website is automatically updated whenever a commit is pushed to this repository. |
| 26 | + |
| 27 | +[TODO] Whenever a new release of the PHPCompatibility package is tagged, the documentation which is based on the source code of PHPCompatibility is automatically re-generated using the [PHPCS-docs](https://github.com/PHPCSStandards/phpcs-docs) generator package and committed to this repository via a GitHub actions workflow. |
| 28 | + |
| 29 | + |
| 30 | +## Testing the website locally |
| 31 | + |
| 32 | +* Install a full [Ruby development environment](https://jekyllrb.com/docs/installation/) |
| 33 | +* Clone this repository |
| 34 | +* Go to the root directory of the clone of this repository |
| 35 | +* Run `bundle update` |
| 36 | +* Run `bundle exec jekyll serve` |
| 37 | +* You should now be able to open the website in your preferred browser at: http://localhost:4000/ |
| 38 | + |
| 39 | +For more information, see the [documentation on testing a GitHub Pages site locally](https://docs.github.com/en/github/working-with-github-pages/testing-your-github-pages-site-locally-with-jekyll). |
| 40 | + |
| 41 | + |
| 42 | +### Typical issues you may run into when testing the site locally |
| 43 | + |
| 44 | +#### The GitHub API credentials you provided aren't valid. |
| 45 | + |
| 46 | +Follow [these instructions](https://github.com/jekyll/github-metadata/blob/master/docs/authentication.md) on getting an access token set up. |
| 47 | + |
| 48 | + |
| 49 | + |
0 commit comments