diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bcd75bc..624d63f 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -72,9 +72,29 @@ php-cs-fixer fix --verbose #### The documentation -The documentation is mostly written with the `rst` format. You can test the doc rendering with the `make docs` command. +The documentation is mostly written with the `rst` format, and can be found in the `Resources/doc` directory. +You can test the doc rendering with the `make docs` command, but to do this, you will need [Sphinx][sphinx_install]. +Just like php dependencies can be managed with Composer, python dependencies can be managed with [pip][pip_install]. +To get sphinx, simply run the following command. + +```bash +pip install --requirement Resources/doc/requirements.txt --user +``` + +Some python binaries should be downloaded in `~/.local/bin`, +[modify your `$PATH` environment variable](http://www.linfo.org/path_env_var.html) +so that it contains this path and then, from the root of the project, run `make docs` + +If `make docs` is successful, you should be able to see your modifications: + +```bash +$YOUR_FAVORITE_BROWSER Resources/doc/_build/html/index.html +``` If your PR contains a new feature, you must add documentation for it. +Of course, you can also create PRs consisting only in documentation changes. + +Documentation contributions should comply with [the Symfony documentation standards][sf_docs_standards]. #### The tests @@ -317,3 +337,7 @@ This is a consensus made on #4242 in addition to #1337. We agreed that blank color is boring and so deja vu. Pink is the new way to do. ``` (Obviously, this commit is fake. :wink:) + +[sphinx_install]: http://www.sphinx-doc.org/en/stable/ +[pip_install]: https://pip.pypa.io/en/stable/installing/ +[sf_docs_standards]: https://symfony.com/doc/current/contributing/documentation/standards.html