Improve php-src docs sphinx build, also on *nix #16743

In 19d2b84 ("Create book for docs", 2024-01-30) the build of the php-src documentation has been introduced. It is based on reStructuredText (rst) [Docutils] for its source files, this stems from the sphinx-build utility in use to build the static HTML pages of the php-src documentation. The maximum line length of these text files has been set to 100 characters. This formatting constraint is applied with the rstfmt utility [rstfmt] via its invocation (documented in CI build instructions and README.md:) rstfmt -w 100 source The `-w, --width` option takes a WIDTH argument that is "the target line length in characters" (cf. `rstfmt --help`.) There is also an `--ext EXT` argument option, that is "the extension of files to look at when passed a directory" ("source" is the name of a directory in the invocation above) and defaults to "rst". Henceforth, the editor configuration [EditorConfig] can benefit from documenting this expectation in the repositories .editorconfig file, which has been introduced already earlier in 5c38fbe ("Added editorconfig file", 2016-06-26). [Docutils]: https://docutils.sourceforge.io/index.html "Docutils: Documentation Utilities — Written in Python, for General- and Special-Purpose Use" [rstfmt]: https://github.com/dzhu/rstfmt "A formatter for reStructuredText" [EditorConfig]: https://editorconfig.org/ "EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs"

In 19d2b84 ("Create book for docs", 2024-01-30) the php-src documentation (php-src docs) build has been introduced, yet the build instructions, namely `make html`, did not yield the expected results within the parenting setup of the php-src project on *nix systems. The reason is that the `make html` build instruction does not execute the make.bat file which contains the recipe to build the static HTML pages. This is because — different to Windows systems — *nix systems do not have the concept of [COMSPEC] etc. for executables, and therefore we cannot expect for build scripts an interpreter for the batch file. Adding a Makefile suffices to recover the build of php-src ./docs on a *nix system. NOTE: The "help" target has been intentionally left out as this Sphinx builder [1] (with the same name) is not available in the configuration, nor in use in CI (.github/workflows/docs.yml), and otherwise appeared undocumented. Consequentially, the makefile goal does not include it, as well as a target for any other unspecfied builder. [COMSPEC]: https://en.wikipedia.org/wiki/COMSPEC "COMSPEC or ComSpec is one of the environment variables used in DOS, OS/2 and Windows, which normally points to the command line interpreter, which is by default COMMAND.COM in DOS,[1] Windows 95, 98, and ME or CMD.EXE in OS/2 and Windows NT. — Wikipedia" [1]: https://www.sphinx-doc.org/en/master/usage/builders/index.html "Built-in Sphinx builders"

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"

For the configured Awesome Sphinx Theme [1] highlighting extension, the sphinx-build currently yields the following diagnostics: WARNING: while setting up extension sphinxawesome_theme.highlighting: \ You no longer have to include the `sphinxawsome_theme.highlighting` \ extension. This extension will be removed in the next major release. (via `make html`, the configuration file is `source/conf.py`.) The diagnostic message was introduced by sphinxawesome-theme 5.2.0, released May 31, 2024. [2], [3] Removing the extension from the list of extensions in the configuration file levitates. No changes to requirements.txt, the extension was transitive as bundled by the Awesome Sphinx Theme [1], and 5.2.0 deprecates it with the new feature to "Support `pygments_style_dark` option that allows you to set a different syntax highlighting scheme in light and dark modes." [3] [1]: https://sphinxawesome.xyz/ "Awesome Sphinx Theme — Create functional and beautiful websites for your documentation with Sphinx." [2]: https://pypi.org/project/sphinxawesome-theme/5.2.0/#history [3]: https://github.com/kai687/sphinxawesome-theme/releases/tag/5.2.0

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Improve php-src docs sphinx build, also on *nix #16743

Improve php-src docs sphinx build, also on *nix #16743

Commits on Nov 9, 2024

Improve php-src docs sphinx build, also on *nix #16743

Are you sure you want to change the base?

Improve php-src docs sphinx build, also on *nix #16743

Commits on Nov 9, 2024