From 193b0b8542d102414376e3a0185ca66b4bd245e2 Mon Sep 17 00:00:00 2001
From: "Hans Krentel (hakre)" <hanskrentel@yahoo.de>
Date: Sat, 9 Nov 2024 23:32:15 +0100
Subject: [PATCH] Bind requirements.txt for php-src docs build
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

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"
---
 .github/workflows/docs.yml |  2 +-
 docs/README.md             | 19 ++++++++++++-------
 docs/requirements.txt      |  4 ++++
 3 files changed, 17 insertions(+), 8 deletions(-)
 create mode 100644 docs/requirements.txt

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
index 2254b8f037e54..2eae9439f250d 100644
--- a/.github/workflows/docs.yml
+++ b/.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: rstfmt --check -w 100 docs/source
       - name: Publish
diff --git a/docs/README.md b/docs/README.md
index fbd58155a5141..3c0d7ddd2bcc3 100644
--- a/docs/README.md
+++ b/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.
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000000000..ca19fe15c2e05
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,4 @@
+Sphinx
+sphinx-design
+sphinxawesome-theme
+rstfmt