Bind requirements.txt for php-src docs build

Define the required packages to install for the php-src docs build in
the docs/requirements.txt file:

1) Sphinx
2) sphinx-design
3) sphinxawesome-theme
4) rstfmt

This should also later on ease the use of a requirements_frozen.txt
file to pin the build dependencies if needed/wanted.

Additionally, some formatting corrections in README.md (based on the
profile in .editorconfig) as well as adding the recommendation to use
a Python virtual environment. Python3 and Pip were already named, and
with Python3 there is the venv module (Python 3.3; Sep 2012) to manage
these so-called python virtual environments [venv], which are commonly
a preferred way to install dependencies within development projects
and build systems.

[venv]: https://docs.python.org/3/library/venv.html "venv — Creation of virtual environments — Python documentation"

Author: hakre

.github/workflows/docs.yml

@@ -19,7 +19,7 @@ jobs:
       - name: git checkout
         uses: actions/checkout@v4
       - name: Install dependencies
-        run: pip install sphinx-design sphinxawesome-theme rstfmt
+        run: pip install -r docs/requirements.txt
       - name: Check formatting
         run: make -C docs check-formatting
       - name: Publish

docs/README.md

@@ -1,9 +1,10 @@
 # php-src docs
 
 This is the home of the php-src internal documentation, hosted at
-[php.github.io/php-src/](https://php.github.io/php-src/). It is in very early stages, but is
-intended to become the primary place where new information about php-src is documented. Over time,
-it is expected to replace various mediums like:
+[php.github.io/php-src/](https://php.github.io/php-src/). It is in very early
+stages, but is intended to become the primary place where new information about
+php-src is documented. Over time, it is expected to replace various mediums
+like:
 
 * https://www.phpinternalsbook.com/
 * https://wiki.php.net/internals
@@ -14,11 +15,15 @@ it is expected to replace various mediums like:
 `python` 3 and `pip` are required.
 
 ```bash
-pip install sphinx sphinx-design sphinxawesome-theme
+cd docs
+# Recommended: Initialize and activate a Python virtual environment
+pip install --upgrade pip
+pip install -r requirements.txt
 make html
 ```
 
-That's it! You can view the documentation under `./build/html/index.html` in your browser.
+That's it! You can view the documentation under `./build/html/index.html` in
+your browser.
 
 ## Formatting
 
@@ -29,5 +34,5 @@ The files in this documentation are formatted using the
 rstfmt -w 100 source
 ```
 
-This tool is not perfect. It breaks on custom directives, so we might switch to either a fork or
-something else in the future.
+This tool is not perfect. It breaks on custom directives, so we might switch to
+either a fork or something else in the future.

docs/requirements.txt

@@ -0,0 +1,4 @@
+Sphinx
+sphinx-design
+sphinxawesome-theme
+rstfmt