Skip to content

Commit 7268da9

Browse files
haszihaszi
haszi
and
haszi
authored
Add contribution guidelines and project overview (#124)
* Add documentation project overview * Add documentation contribution guidelines * Update documentation CONTRIBUTING file Change wording in most parts. Make reporting a bug section a list of bullet points. Rewrite the setup section to be simpler. Split validating and rendering the documentation into their own sections. Add additional information section with links to pages that have information that was not included on this page. --------- Co-authored-by: haszi <[email protected]>
1 parent 2c9d165 commit 7268da9

File tree

2 files changed

+307
-0
lines changed

2 files changed

+307
-0
lines changed

‎CONTRIBUTING_DOCS.md‎

Lines changed: 217 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,217 @@
1+
# Contributing to the PHP Documentation
2+
3+
You can easily contribute to the PHP documentation
4+
by either [reporting a bug](#report-a-bug)
5+
or by fixing one by [submitting a pull request](#submit-a-pull-request).
6+
As all the repositories are hosted on GitHub,
7+
you will need a GitHub account to do either of these.
8+
9+
## Report a Bug
10+
11+
If you have found a bug on any of the PHP documentation pages,
12+
you can file a bug report by doing the following:
13+
14+
- click the "Report a Bug" link in the "Improve This Page" section
15+
on the bottom of the page
16+
- log into GitHub
17+
- add a short description of the bug in the title textbox
18+
- add all necessary details to the description textarea
19+
- click the "Submit new issue" button to file your bug report
20+
21+
## Submit a Pull Request
22+
23+
There are two ways to make changes to the documentation:
24+
- make [minor changes](#minor-changes) by editing files on GitHub
25+
- make [more complex changes](#more-complex-changes--building-the-php-documentation)
26+
and validate/build the documentation locally on your computer
27+
28+
## Minor changes
29+
30+
To make trivial changes (typos, shorter wording changes or adding/removing short segments)
31+
all one needs is a web-browser and a GitHub account and doing the following:
32+
33+
- click the "Submit a Pull Request" link in the "Improve This Page" section
34+
on the bottom of the documentation page
35+
- log into GitHub
36+
- fork the repository (if you have not forked it already)
37+
- make changes
38+
- click the "Commit changes" button
39+
- add a commit message (short description of the change) into the "Commit message" textbox
40+
- write a longer description in the "Extended description" textarea, if needed
41+
- click the "Propose changes" button
42+
- review your changes and click "Create pull request" button
43+
44+
The repository will run a few basic checks on the changes
45+
(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.)
46+
and your PR is ready to be discussed with and merged by the maintainers.
47+
48+
## More Complex Changes / Building the PHP documentation
49+
50+
To build and view the documentation after making more extensive changes
51+
(e.g. adding entire sections or files), you will need to
52+
[clone some of the tooling](#set-up-a-development-environment)
53+
(doc-base, phd and possibly web-php)
54+
in addition to the language repository you want to
55+
[make the changes](#make-changes-to-the-documentation) to.
56+
You need to [validate the changes](#validate-the-documentation)
57+
and you can (but do not have to) [render the documentation](#render-the-documentation)
58+
before you [open a PR](#commit-changes-and-open-a-pr).
59+
60+
If you'd like to know more about what each repository is
61+
and/or how PHP's documentation is built please refer to
62+
this [overview](https://github.com/php/doc-base/OVERVIEW.md).
63+
64+
### Requirements
65+
66+
Following this guide to make changes to and build the documentation has the following dependencies:
67+
- PHP 8.0+ with the DOM, libXML2, XMLReader and SQLite3 extensions
68+
- Git
69+
- an IDE or a text editor
70+
71+
### Set up a development environment
72+
73+
#### Basic setup
74+
75+
To start working on the English documentation, you need to fork it on Github
76+
and clone it, doc-base (for validating the XML files) and PhD (for rendering the files).
77+
78+
```shell
79+
git clone https://github.com/<your_github_username>/<your_fork> en
80+
git clone https://github.com/php/doc-base
81+
git clone https://github.com/php/phd
82+
cd en
83+
git remote add upstream https://github.com/php/doc-en
84+
```
85+
where `<your_github_username>` and `<your_fork>` needs to be replaced by
86+
your GitHub username and the name of your for of the English documentation respectively.
87+
Please note that the English documentation has to be cloned into the `en` directory.
88+
89+
To clone any of the translations, replace `doc-en en` at the end of the first line
90+
with the translation you would like to clone
91+
(e.g. `doc-pt_br` for the Brazilian documentation).
92+
As an example, the following shows how to set up the Brazilian documentation:
93+
94+
```shell
95+
git clone https://github.com/<your_github_username>/doc-pt_br
96+
git clone https://github.com/php/doc-base
97+
git clone https://github.com/php/phd
98+
cd doc-pt_br
99+
git remote add upstream https://github.com/php/doc-pt_br
100+
```
101+
where `<your_github_username>` needs to be replaced by your GitHub username.
102+
103+
<details>
104+
<summary>List of languages/repositories</summary>
105+
106+
- [Brazilian Portugues](https://github.com/php/doc-pt_br) (doc-pt_br)
107+
- [Chinese(Simplified)](https://github.com/php/doc-zh) (doc-zh)
108+
- [English](https://github.com/php/doc-en) (doc-en)
109+
- [French](https://github.com/php/doc-fr) (doc-fr)
110+
- [German](https://github.com/php/doc-de) (doc-de)
111+
- [Italian](https://github.com/php/doc-it) (doc-it)
112+
- [Japanese](https://github.com/php/doc-ja) (doc-ja)
113+
- [Polish](https://github.com/php/doc-pl) (doc-pl)
114+
- [Romanian](https://github.com/php/doc-ro) (doc-ro)
115+
- [Russian](https://github.com/php/doc-ru) (doc-ru)
116+
- [Spanish](https://github.com/php/doc-es) (doc-es)
117+
- [Turkish](https://github.com/php/doc-tr) (doc-tr)
118+
- [Ukrainian](https://github.com/php/doc-uk) (doc-uk)
119+
</details>
120+
121+
#### Setting up a local mirror
122+
123+
If you would like to setup a local mirror of the documentation
124+
or you would just like to see how your changes will look like online:
125+
126+
```shell
127+
git clone https://github.com/php/web-php
128+
cd web-php/manual
129+
rm -rf en
130+
ln -s ../../output/php-web en
131+
```
132+
133+
where `../../output/php-web` is the directory the PhD generated .php files are saved at,
134+
relative to the `web-php/manual` directory.
135+
136+
On Windows:
137+
138+
```shell
139+
git clone https://github.com/php/web-php
140+
cd \your\path\to\web-php\manual\
141+
rmdir /S en
142+
mklink /D en \your\path\to\output\web-php
143+
```
144+
145+
where `\your\path\to\output\web-php` is the directory the PhD generated .php files are saved at,
146+
relative to the `\your\path\to\web-php\manual\` directory.
147+
148+
#### Using your local mirror
149+
150+
You can view the documentation by using any web server
151+
but one of the simplest ways is to use PHP's built-in web server:
152+
153+
```shell
154+
cd web-php
155+
php -S localhost:8080 .router.php
156+
```
157+
158+
where `web-php` is the directory web-php has been cloned into.
159+
160+
The manual is now available from http://localhost:8080/manual/en/ in your browser.
161+
162+
### Make changes to the documentation
163+
164+
Make your changes keeping in mind the [style guidelines](http://doc.php.net/tutorial/style.php).
165+
166+
### Validate the documentation
167+
168+
To validate the English documentation (located in the directory `en`), run
169+
```shell
170+
php doc-base/configure.php
171+
```
172+
173+
To validate any other documentation, run
174+
```shell
175+
php doc-base/configure.php --with-lang=doc-lang
176+
```
177+
where `doc-lang` is the name of your language's repository
178+
and the corresponding directory (eg. `doc-de` for German).
179+
180+
*Please note that all validation errors have to be corrected
181+
before opening a PR.*
182+
183+
### Render the documentation
184+
185+
To render the documentation in xhtml format (can be viewed without a web server), run
186+
```shell
187+
php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml
188+
```
189+
190+
To render the documentation in php format (needs a web server and web-php), run
191+
```shell
192+
php phd/render.php --docbook doc-base/.manual.xml --package PHP --format php
193+
```
194+
195+
### Commit changes and open a PR
196+
197+
- commit your changes
198+
- push to your fork
199+
- open a PR in the appropriate language repository
200+
201+
Once you open a PR, the documentation repository will run a few basic checks on the changes
202+
(e.g. whether the XML markup is valid, whether trailing whitespaces are stripped, etc.)
203+
and your PR is ready to be discussed with and merged by the maintainers.
204+
205+
## Additional information
206+
207+
For additional information on contributing to the documentation refer to:
208+
209+
- the [Adding new documentation](http://doc.php.net/tutorial/editing.php)
210+
section of the "Editing manual sources" page
211+
- the [Files structure](http://doc.php.net/tutorial/structure.php)
212+
section of the "Manual sources structure" page
213+
- the [Translating documentation](http://doc.php.net/tutorial/translating.php) page
214+
- the [Style guidelines](http://doc.php.net/tutorial/style.php) page
215+
- the [FAQ](http://doc.php.net/tutorial/faq.php) page
216+
- the [Why we care about whitespace](http://doc.php.net/tutorial/whitespace.php) page
217+
- doc-base's [README](https://github.com/php/doc-base/blob/master/README.md)

‎OVERVIEW.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# The PHP Documentation
2+
3+
The PHP documentation is built from XML files and render into PHP files
4+
that are available on the [php.net/manual](https://php.net/manual/en) pages.
5+
All parts of the process live in the following GitHub repositories:
6+
7+
- [**doc-\* repos**](#the-english-language-documentation-and-its-translations):
8+
these are the repositories where all the information on documentation pages live
9+
and this is where changes to the wording and/or structure
10+
of the documentation's content can be made
11+
- [**doc-base**](#doc-base): validates and pre-processes the language files
12+
- [**PhD**](#phd): renders pages into .php files which include information on the files
13+
and function calls to include the documentation page headers and footers
14+
- [**web-php**](#web-php): serves up the .php files generated by PhD
15+
and includes the functions to generate page headers and footers
16+
(to include contribution call-out and user notes)
17+
18+
## The English Language Documentation And Its Translations
19+
20+
These repositories contain PHP's documentation in their respective languages
21+
and these are where changes to the content/structure
22+
of the [php.net's documentation pages](https://www.php.net/docs.php) are made.
23+
24+
Please refer to [doc-base's](https://github.com/php/doc-base)
25+
[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md)
26+
on how to contribute to the documentation.
27+
28+
## doc-base
29+
30+
[doc-base](https://github.com/php/doc-base) validates and combines the documentations' XML files.
31+
It includes a skeleton/main table of contents of the PHP documentation (index.php)
32+
and the `configure.php` script which processes the documentation:
33+
- pulls version info file from repo files
34+
- starting from the skeleton/main table of contents file, it iterates over all files in the language repository and includes all elements with the appropriate IDs
35+
- pulls modification history file
36+
- generates the file entities from the source language directory and writes these back into the same directory
37+
- loads the combined XML file into memory
38+
- runs/executes all XInclude/XPointer links
39+
- subtitutes entities
40+
- validates the document based on its DTD
41+
42+
Please refer to [doc-base's](https://github.com/php/doc-base)
43+
[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md)
44+
on further details on how to use doc-base.
45+
46+
## PhD
47+
48+
[PhD](https://github.com/php/phd) (PHP DocBook) renders the combined XML file,
49+
the version file and modification history files generated/copied by [doc-base](https://github.com/php/doc-base)
50+
into the final PHP documentation pages.
51+
52+
While PhD is capable of generating the documentation in a number of formats,
53+
the PHP documentation website is using the format that generates .php files.
54+
This format adds PHP code in each file that contains information on the current page
55+
(e.g. title, breadcrumbs, source file name/path, last modified date/time, contributor list)
56+
and calls to setting up the header and footer for the page.
57+
58+
It's important to note that the function calls included in the pages here
59+
are for functions that are defined in [web-php](https://github.com/php/web-php).
60+
A new functionality added to [web-php](https://github.com/php/web-php) can only be used
61+
if the appropriate format in PhD is modified to include the function call.
62+
63+
Other than the above PhD also does the following:
64+
- writes the search-index and search-description json files
65+
- copies (by default downloads) css files into the output directory
66+
- copies images to the images directory
67+
- generates and saves the TOC (table of contents) files
68+
(the TOC/navbar on the right side of the documentation pages)
69+
70+
Please refer to [doc-base's](https://github.com/php/doc-base)
71+
[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md)
72+
on further details on how to use PhD.
73+
74+
## web-php
75+
76+
[web-php](https://github.com/php/web-php) is the repository that PHP's web servers actually run
77+
(ie. almost everything accesible on [php.net](https://php.net)).
78+
79+
This repository includes the functions that generate the header (top navigation and search bar)
80+
and footer (copyright, privacy policy, etc.) for most php.net pages
81+
and it also includes the functions that generate the additional header (breadcrumbs, language dropdown, etc.)
82+
and footer (contribution and user notes sections) of documentation pages.
83+
84+
It uses the css, image, TOC and search index/description files copied/generated by PhD
85+
to serve up images/css files, generate the right side TOC/navbar on the documentation pages
86+
and make the search bar on [php.net](https://php.net) work.
87+
88+
Please refer to [doc-base's](https://github.com/php/doc-base)
89+
[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md)
90+
on further details on how to use web-php.

0 commit comments

Comments
 (0)