Skip to content

Commit

Permalink
Make indentation consistent
Browse files Browse the repository at this point in the history
  • Loading branch information
haszi committed May 20, 2024
1 parent 00d69d0 commit 054bebd
Showing 1 changed file with 71 additions and 68 deletions.
139 changes: 71 additions & 68 deletions CONTRIBUTING_DOCS.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,35 +11,35 @@ you will need a GitHub account to do either of these.
If you have found a bug on any of the PHP documentation pages,
you can file a bug report by doing the following:

- click the "Report a Bug" link in the "Improve This Page" section
- click the "Report a Bug" link in the "Improve This Page" section
on the bottom of the page
- log into GitHub
- add a short description of the bug in the title textbox
- add all necessary details to the description textarea
- click the "Submit new issue" button to file your bug report
- log into GitHub
- add a short description of the bug in the title textbox
- add all necessary details to the description textarea
- click the "Submit new issue" button to file your bug report

## Submit a Pull Request

There are two ways to make changes to the documentation:
- make [minor changes](#minor-changes) by editing files on GitHub
- make [more complex changes](#more-complex-changes--building-the-php-documentation)
- make [minor changes](#minor-changes) by editing files on GitHub
- make [more complex changes](#more-complex-changes--building-the-php-documentation)
and validate/build the documentation locally on your computer

## Minor changes

To make trivial changes (typos, shorter wording changes or adding/removing short segments)
all one needs is a web-browser and a GitHub account and doing the following:

- click the "Submit a Pull Request" link in the "Improve This Page" section
on the bottom of the documentation page
- log into GitHub
- fork the repository (if you have not forked it already)
- make changes
- click the "Commit changes" button
- add a commit message (short description of the change) into the "Commit message" textbox
- write a longer description in the "Extended description" textarea, if needed
- click the "Propose changes" button
- review your changes and click "Create pull request" button
- click the "Submit a Pull Request" link in the "Improve This Page" section
on the bottom of the documentation page
- log into GitHub
- fork the repository (if you have not forked it already)
- make changes
- click the "Commit changes" button
- add a commit message (short description of the change) into the "Commit message" textbox
- write a longer description in the "Extended description" textarea, if needed
- click the "Propose changes" button
- review your changes and click "Create pull request" button

The repository will run a few basic checks on the changes
(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.)
Expand All @@ -64,23 +64,24 @@ this [overview](https://github.com/php/doc-base/OVERVIEW.md).
### Requirements

Following this guide to make changes to and build the documentation has the following dependencies:
- PHP 8.0+ with the DOM, libXML2, XMLReader and SQLite3 extensions
- Git
- an IDE or a text editor
- PHP 8.0+ with the DOM, libXML2, XMLReader and SQLite3 extensions
- Git
- an IDE or a text editor

### Set up a development environment

#### Basic setup

To start working on the English documentation, you need to fork it on Github
and clone it, doc-base (for validating the XML files) and PhD (for rendering the files).

```shell
git clone https://github.com/<your_github_username>/<your_fork> en
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd en
git remote add upstream https://github.com/php/doc-en
```
```shell
git clone https://github.com/<your_github_username>/<your_fork> en
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd en
git remote add upstream https://github.com/php/doc-en
```
where `<your_github_username>` and `<your_fork>` needs to be replaced by
your GitHub username and the name of your for of the English documentation respectively.
Please note that the English documentation has to be cloned into the `en` directory.
Expand All @@ -90,13 +91,13 @@ with the translation you would like to clone
(e.g. `doc-pt_br` for the Brazilian documentation).
As an example, the following shows how to set up the Brazilian documentation:

```shell
git clone https://github.com/<your_github_username>/doc-pt_br
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd doc-pt_br
git remote add upstream https://github.com/php/doc-pt_br
```
```shell
git clone https://github.com/<your_github_username>/doc-pt_br
git clone https://github.com/php/doc-base
git clone https://github.com/php/phd
cd doc-pt_br
git remote add upstream https://github.com/php/doc-pt_br
```
where `<your_github_username>` needs to be replaced by your GitHub username.

<details>
Expand All @@ -122,40 +123,41 @@ where `<your_github_username>` needs to be replaced by your GitHub username.
If you would like to setup a local mirror of the documentation
or you would just like to see how your changes will look like online:

```shell
git clone https://github.com/php/web-php
cd web-php/manual
rm -rf en
ln -s ../../output/php-web en
```
```shell
git clone https://github.com/php/web-php
cd web-php/manual
rm -rf en
ln -s ../../output/php-web en
```

where `../../output/php-web` is the directory the PhD generated .php files are saved at,
relative to the `web-php/manual` directory.
where `../../output/php-web` is the directory the PhD generated .php files are saved at,
relative to the `web-php/manual` directory.

On Windows:

```shell
git clone https://github.com/php/web-php
cd \your\path\to\web-php\manual\
rmdir /S en
mklink /D en \your\path\to\output\web-php
```
```shell
git clone https://github.com/php/web-php
cd \your\path\to\web-php\manual\
rmdir /S en
mklink /D en \your\path\to\output\web-php
```

where `\your\path\to\output\web-php` is the directory the PhD generated .php files are saved at,
relative to the `\your\path\to\web-php\manual\` directory.
where `\your\path\to\output\web-php` is the directory the PhD generated .php files are saved at,
relative to the `\your\path\to\web-php\manual\` directory.

#### Using your local mirror
You can view the documentation by using any web server
but one of the simplest ways is to use PHP's built-in web server:

```shell
cd web-php
php -S localhost:8080 .router.php
```
You can view the documentation by using any web server
but one of the simplest ways is to use PHP's built-in web server:

```shell
cd web-php
php -S localhost:8080 .router.php
```

where `web-php` is the directory web-php has been cloned into.
where `web-php` is the directory web-php has been cloned into.

The manual is now available from http://localhost:8080/manual/en/ in your browser.
The manual is now available from http://localhost:8080/manual/en/ in your browser.

### Make changes to the documentation

Expand Down Expand Up @@ -191,9 +193,10 @@ php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php
```

### Commit changes and open a PR
- commit your changes
- push to your fork
- open a PR in the appropriate language repository

- commit your changes
- push to your fork
- open a PR in the appropriate language repository

Once you open a PR, the documentation repository will run a few basic checks on the changes
(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.)
Expand All @@ -203,12 +206,12 @@ and your PR is ready to be discussed with and merged by the maintainers.

For additional information on contributing to the documentation refer to:

- the [Adding new documentation](http://doc.php.net/tutorial/editing.php)
- the [Adding new documentation](http://doc.php.net/tutorial/editing.php)
section of the "Editing manual sources" page
- the [Files structure](http://doc.php.net/tutorial/structure.php)
- the [Files structure](http://doc.php.net/tutorial/structure.php)
section of the "Manual sources structure" page
- the [Translating documentation](http://doc.php.net/tutorial/translating.php) page
- the [Style guidelines](http://doc.php.net/tutorial/style.php) page
- the [FAQ](http://doc.php.net/tutorial/faq.php) page
- the [Why we care about whitespace](http://doc.php.net/tutorial/whitespace.php) page
- doc-base's [README](https://github.com/php/doc-base/blob/master/README.md)
- the [Translating documentation](http://doc.php.net/tutorial/translating.php) page
- the [Style guidelines](http://doc.php.net/tutorial/style.php) page
- the [FAQ](http://doc.php.net/tutorial/faq.php) page
- the [Why we care about whitespace](http://doc.php.net/tutorial/whitespace.php) page
- doc-base's [README](https://github.com/php/doc-base/blob/master/README.md)

0 comments on commit 054bebd

Please sign in to comment.