diff --git a/CONTRIBUTING_DOCS.md b/CONTRIBUTING_DOCS.md new file mode 100644 index 000000000..73e3cd48d --- /dev/null +++ b/CONTRIBUTING_DOCS.md @@ -0,0 +1,217 @@ +# Contributing to the PHP Documentation + +You can easily contribute to the PHP documentation +by either [reporting a bug](#report-a-bug) +or by fixing one by [submitting a pull request](#submit-a-pull-request). +As all the repositories are hosted on GitHub, +you will need a GitHub account to do either of these. + +## Report a Bug + +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 + 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 + +## 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) + 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 + +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.) +and your PR is ready to be discussed with and merged by the maintainers. + +## More Complex Changes / Building the PHP documentation + +To build and view the documentation after making more extensive changes +(e.g. adding entire sections or files), you will need to +[clone some of the tooling](#set-up-a-development-environment) +(doc-base, phd and possibly web-php) +in addition to the language repository you want to +[make the changes](#make-changes-to-the-documentation) to. +You need to [validate the changes](#validate-the-documentation) +and you can (but do not have to) [render the documentation](#render-the-documentation) +before you [open a PR](#commit-changes-and-open-a-pr). + +If you'd like to know more about what each repository is +and/or how PHP's documentation is built please refer to +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 + +### 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// 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 `` and `` 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. + +To clone any of the translations, replace `doc-en en` at the end of the first line +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//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 `` needs to be replaced by your GitHub username. + +
+ List of languages/repositories + + - [Brazilian Portugues](https://github.com/php/doc-pt_br) (doc-pt_br) + - [Chinese(Simplified)](https://github.com/php/doc-zh) (doc-zh) + - [English](https://github.com/php/doc-en) (doc-en) + - [French](https://github.com/php/doc-fr) (doc-fr) + - [German](https://github.com/php/doc-de) (doc-de) + - [Italian](https://github.com/php/doc-it) (doc-it) + - [Japanese](https://github.com/php/doc-ja) (doc-ja) + - [Polish](https://github.com/php/doc-pl) (doc-pl) + - [Romanian](https://github.com/php/doc-ro) (doc-ro) + - [Russian](https://github.com/php/doc-ru) (doc-ru) + - [Spanish](https://github.com/php/doc-es) (doc-es) + - [Turkish](https://github.com/php/doc-tr) (doc-tr) + - [Ukrainian](https://github.com/php/doc-uk) (doc-uk) +
+ +#### Setting up a local mirror + +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 +``` + +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 +``` + +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 +``` + +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. + +### Make changes to the documentation + +Make your changes keeping in mind the [style guidelines](http://doc.php.net/tutorial/style.php). + +### Validate the documentation + +To validate the English documentation (located in the directory `en`), run +```shell +php doc-base/configure.php +``` + +To validate any other documentation, run +```shell +php doc-base/configure.php --with-lang=doc-lang +``` +where `doc-lang` is the name of your language's repository +and the corresponding directory (eg. `doc-de` for German). + +*Please note that all validation errors have to be corrected +before opening a PR.* + +### Render the documentation + +To render the documentation in xhtml format (can be viewed without a web server), run +```shell +php phd/render.php --docbook doc-base/.manual.xml --package PHP --format xhtml +``` + +To render the documentation in php format (needs a web server and web-php), run +```shell +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 + +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.) +and your PR is ready to be discussed with and merged by the maintainers. + +## Additional information + +For additional information on contributing to the documentation refer to: + +- 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) + 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) diff --git a/OVERVIEW.md b/OVERVIEW.md new file mode 100644 index 000000000..b7d9dc7fa --- /dev/null +++ b/OVERVIEW.md @@ -0,0 +1,90 @@ +# The PHP Documentation + +The PHP documentation is built from XML files and render into PHP files +that are available on the [php.net/manual](https://php.net/manual/en) pages. +All parts of the process live in the following GitHub repositories: + +- [**doc-\* repos**](#the-english-language-documentation-and-its-translations): + these are the repositories where all the information on documentation pages live + and this is where changes to the wording and/or structure + of the documentation's content can be made +- [**doc-base**](#doc-base): validates and pre-processes the language files +- [**PhD**](#phd): renders pages into .php files which include information on the files + and function calls to include the documentation page headers and footers +- [**web-php**](#web-php): serves up the .php files generated by PhD + and includes the functions to generate page headers and footers + (to include contribution call-out and user notes) + +## The English Language Documentation And Its Translations + +These repositories contain PHP's documentation in their respective languages +and these are where changes to the content/structure +of the [php.net's documentation pages](https://www.php.net/docs.php) are made. + +Please refer to [doc-base's](https://github.com/php/doc-base) +[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md) +on how to contribute to the documentation. + +## doc-base + +[doc-base](https://github.com/php/doc-base) validates and combines the documentations' XML files. +It includes a skeleton/main table of contents of the PHP documentation (index.php) +and the `configure.php` script which processes the documentation: +- pulls version info file from repo files +- 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 +- pulls modification history file +- generates the file entities from the source language directory and writes these back into the same directory +- loads the combined XML file into memory +- runs/executes all XInclude/XPointer links +- subtitutes entities +- validates the document based on its DTD + +Please refer to [doc-base's](https://github.com/php/doc-base) +[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md) +on further details on how to use doc-base. + +## PhD + +[PhD](https://github.com/php/phd) (PHP DocBook) renders the combined XML file, +the version file and modification history files generated/copied by [doc-base](https://github.com/php/doc-base) +into the final PHP documentation pages. + +While PhD is capable of generating the documentation in a number of formats, +the PHP documentation website is using the format that generates .php files. +This format adds PHP code in each file that contains information on the current page +(e.g. title, breadcrumbs, source file name/path, last modified date/time, contributor list) +and calls to setting up the header and footer for the page. + +It's important to note that the function calls included in the pages here +are for functions that are defined in [web-php](https://github.com/php/web-php). +A new functionality added to [web-php](https://github.com/php/web-php) can only be used +if the appropriate format in PhD is modified to include the function call. + +Other than the above PhD also does the following: +- writes the search-index and search-description json files +- copies (by default downloads) css files into the output directory +- copies images to the images directory +- generates and saves the TOC (table of contents) files + (the TOC/navbar on the right side of the documentation pages) + +Please refer to [doc-base's](https://github.com/php/doc-base) +[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md) +on further details on how to use PhD. + +## web-php + +[web-php](https://github.com/php/web-php) is the repository that PHP's web servers actually run +(ie. almost everything accesible on [php.net](https://php.net)). + +This repository includes the functions that generate the header (top navigation and search bar) +and footer (copyright, privacy policy, etc.) for most php.net pages +and it also includes the functions that generate the additional header (breadcrumbs, language dropdown, etc.) +and footer (contribution and user notes sections) of documentation pages. + +It uses the css, image, TOC and search index/description files copied/generated by PhD +to serve up images/css files, generate the right side TOC/navbar on the documentation pages +and make the search bar on [php.net](https://php.net) work. + +Please refer to [doc-base's](https://github.com/php/doc-base) +[contribution guidlines](https://github.com/php/doc-base/CONTRIBUTING_DOCS.md) +on further details on how to use web-php.