docs: Internals Book improvements (03)

.github/workflows/docs.yml

@@ -20,8 +20,6 @@ jobs:
         uses: actions/checkout@v6
       - name: Install dependencies
         run: pip install -r docs/requirements.txt
-      - name: Check formatting
-        run: make -C docs check-formatting
       - name: Publish
         if: github.event_name == 'push'
         uses: sphinx-notes/pages@v3

docs-old/output-api.md

@@ -126,11 +126,3 @@ context:
         nor removable
     PHP_OUTPUT_HANDLER_HOOK_DISABLE
         the second arg is ignored; marks the output handler as disabled
-
-## Open questions
-
-* Should the userland API be adjusted and unified?
-
-Many bits of the manual (and very first implementation) do not comply with the
-behaviour of the current (to be obsoleted) code, thus should the manual or the
-behaviour be adjusted?

docs/Makefile

@@ -7,30 +7,16 @@ SPHINXBUILD ?= sphinx-build
 
 SOURCEDIR = source
 BUILDDIR = build
-RSTFMT = rstfmt
-RSTFMTFLAGS = -w 100
-
-rwildcard = $(foreach d,$(wildcard $(1:=/*)),$(call rwildcard,$d,$2) $(filter $(subst *,%,$2),$d))
-FILES = $(call rwildcard,$(SOURCEDIR),*.rst)
 
 all : html
 
-.PHONY : check-formatting clean html preflight
+.PHONY : clean html
 .SUFFIXES : # Disable legacy behavior
 
-check-formatting :
-	$(RSTFMT) $(RSTFMTFLAGS) --check $(SOURCEDIR)
-
 clean :
-	rm -rf -- $(wildcard $(SOURCEDIR)/.~ $(BUILDDIR))
+	rm -rf -- $(BUILDDIR)
 
-html : preflight
+html :
 	$(SPHINXBUILD) -M $@ $(SOURCEDIR) $(BUILDDIR)
 	@printf 'Browse the \e]8;;%s\e\\%s\e]8;;\e\\.\n' \
 		"file://$(abspath $(BUILDDIR))/$@/index.$@" "php-src html docs locally"
-
-preflight : $(SOURCEDIR)/.~
-
-$(SOURCEDIR)/.~ : $(FILES)
-	$(RSTFMT) $(RSTFMTFLAGS) $?
-	touch $@

docs/README.md

@@ -27,12 +27,4 @@ your browser.
 
 ## Formatting
 
-The files in this documentation are formatted using the
-[``rstfmt``](https://github.com/dzhu/rstfmt) tool.
-
-```bash
-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.
+Formatting is temporarily not enforced during the Markdown migration.

docs/requirements.txt

@@ -1,4 +1,4 @@
 Sphinx
+myst-parser>=5.1
 sphinx-design
 sphinxawesome-theme
-rstfmt

docs/source/conf.py

@@ -15,9 +15,18 @@
 project = 'php-src docs'
 author = 'The PHP Group'
 extensions = [
+    'myst_parser',
     'sphinx_design',
     'sphinx.ext.autosectionlabel',
 ]
+exclude_patterns = ['**/*TODO.md']
+myst_enable_extensions = [
+    'alert',
+    'gfm_autolink',
+    'strikethrough',
+    'tasklist',
+]
+myst_heading_anchors = 6
 templates_path = ['_templates']
 html_theme = 'sphinxawesome_theme'
 html_static_path = ['_static']

docs/source/core/TODO.md

@@ -0,0 +1,8 @@
+Core TODO
+
+Pages to add:
+
+- Parser and AST: grammar generation, AST representation, compilation boundaries,
+  and important extension points.
+- Virtual Machine: opcode execution, operands, call frames, and VM variants.
+- Object Handlers: handler contracts, object storage, and common ownership traps.

docs/source/core/data-structures/TODO.md

@@ -0,0 +1,4 @@
+Data Structures TODO
+
+- Add a HashTable page covering ownership, iteration, mutation, and common APIs.
+- Expand the zval macro table and document the remaining internal zval types.

docs/source/core/data-structures/index.md

@@ -0,0 +1,12 @@
+# Data structures
+
+```{toctree}
+   :hidden:
+
+zval
+reference-counting
+zend_string
+zend_constant
+```
+
+This section provides an overview of the core data structures used in php-src.