Document the development process for the PHPUnit documentation

[sebastianbergmann]

• [x] Figure out a strategy (branching and tagging) for maintaining multiple versions of the documentation (ReadTheDocs does not render branches other than master and requires tags for alternative versions)
• [x] Document how to contribute to an existing language edition of the documentation
• [ ] Document how to build the documentation on a local machine
• [x] Document how to start a new language edition of the documentation

[glengemann]

Hi! I am translating into Spanish the PHPUnit's documentation. The chapter 2 and 8, writing test and database tests respectively, are already translated. Could you create a git project?

[sebastianbergmann]

You should have access to the newly created https://github.com/sebastianbergmann/phpunit-documentation-spanish repository now.

[keradus]

somehow related to the process.. does docs for legacy PHPUnit versions (like 5) still maintained, or they are frozen ?

[sebastianbergmann]

The documentation for PHPUnit < 7 is frozen.

[keradus]

Thanks for info :+1:

[sebastianheuer]

Regarding handling multiple version we figured that having a branch for each released version works best. So now there are 7.0 and 7.1 branches which readthedocs.org will automatically pick up; see http://phpunit.readthedocs.io/en/7.0/ for example.

The same branching will have to be done for all other languages as well to be able to properly switch between translations for a specific version.

[keradus]

bit :+1: for branches

[plucht]

Regarding building the documentation locally, there's not much to add to the current explanation in README.md - just found out there is also a Docker image available, provided by readthedocs.io

[glengemann]

Thanks @plucht, the first time before run make html I need to install some packages (in Debian 9):

The python dependencies and make:

# apt install python-sphinx python-pip make

Then, install Sphinx Theme via pip:

# pip install sphinx_rtd_theme

I do not know if this is the best way. It was not difficult but it was not obvious either.

[keradus]

vide requirements.txt file