Skip to content

Commit cde9f1f

Browse files
iluuu1994iluuu1994
committed
Create mdbook for docs
1 parent 7aa2b62 commit cde9f1f

19 files changed

+656
-0
lines changed

‎.github/workflows/docs.yml

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
name: Docs
2+
on:
3+
push:
4+
branches:
5+
- master
6+
paths:
7+
- docs/*
8+
# FIXME: Remove
9+
pull_request:
10+
branches:
11+
- '**'
12+
paths:
13+
- docs/*
14+
jobs:
15+
deploy:
16+
runs-on: ubuntu-latest
17+
permissions:
18+
pages: write
19+
id-token: write
20+
steps:
21+
- uses: actions/checkout@v4
22+
- name: prettier
23+
run: |
24+
cd docs
25+
npm install
26+
npm run prettier-check
27+
- name: Install mdbook
28+
run: |
29+
tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name')
30+
url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz"
31+
mkdir mdbook
32+
curl -sSL $url | tar -xz --directory=./mdbook
33+
echo `pwd`/mdbook >> $GITHUB_PATH
34+
- name: Build book
35+
run: |
36+
cd docs
37+
mdbook build
38+
- name: Setup Pages
39+
uses: actions/configure-pages@v2
40+
- name: Upload artifact
41+
uses: actions/upload-pages-artifact@v1
42+
with:
43+
path: docs/book
44+
- name: Deploy to GitHub Pages
45+
id: deployment
46+
uses: actions/deploy-pages@v1

‎docs/.editorconfig

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
[*]
2+
end_of_line = lf
3+
insert_final_newline = true
4+
5+
[*.md]
6+
indent_style = space
7+
indent_size = 2
8+
max_line_length = 120

‎docs/.gitignore

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
book
2+
node_modules
3+
package-lock.json

‎docs/.prettierignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
src/miscellaneous/old

‎docs/.prettierrc.json

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
{
2+
"proseWrap": "always"
3+
}

‎docs/LICENSE

Lines changed: 437 additions & 0 deletions
Large diffs are not rendered by default.

‎docs/README.md

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# php-src docs
2+
3+
This is the home of the php-src internal documentation. It is in very early stages, but is intended to become the
4+
primary place where new information about php-src is documented. Over time, it is expected to replace various mediums
5+
like:
6+
7+
* https://www.phpinternalsbook.com/
8+
* https://wiki.php.net/internals
9+
* Blogs from contributors
10+
11+
## Credits
12+
13+
### PHP Internals Book
14+
15+
While the bulk of the work hasn't happened yet, a substantial amount of content is expected to be ported from the PHP
16+
Internals Book.
17+
18+
https://www.phpinternalsbook.com/, [src](https://github.com/phpinternalsbook/PHP-Internals-Book), CC-BY-NC-SA License

‎docs/book.toml

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
[book]
2+
authors = ["The PHP Group"]
3+
language = "en"
4+
multilingual = false
5+
src = "src"
6+
title = "php-src docs"

‎docs/package.json

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
{
2+
"name": "php-src-docs",
3+
"scripts": {
4+
"prettier": "npx prettier --write src",
5+
"prettier-check": "npx prettier --check src"
6+
},
7+
"dependencies": {
8+
"prettier": "^3.2.4"
9+
}
10+
}

‎docs/src/SUMMARY.md

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# Introduction
2+
3+
- [Getting started](./introduction/getting-started.md)
4+
- [Building]()
5+
- [Running tests]()
6+
- [Debugging]()
7+
8+
# Project overview
9+
10+
- [Directory structure]()
11+
- [Interpreter pipeline]()
12+
13+
# Core
14+
15+
- [Overview]()
16+
- [Startup/shutdown]()
17+
- [Data structures]()
18+
- [zval]()
19+
- [zend_string]()
20+
- [zend_array]()
21+
- [zend_object]()
22+
- [Reference counting]()
23+
- [zend_function]()
24+
- [zend_class_entry]()
25+
- [zend_arena]()
26+
- [Scanner]()
27+
- [Parser]()
28+
- [Compiler]()
29+
- [znode]()
30+
- [Comptime]()
31+
- [Delayed opcodes]()
32+
- [Virtual machine]()
33+
- [Stack]()
34+
- [Basic opcodes]()
35+
- [zend_vm_def.h]()
36+
- [Execution]()
37+
- [Exceptions]()
38+
- [Function calls]()
39+
- [Specialization]()
40+
- [Cache slots]()
41+
- [Trampoline]()
42+
- [Opcode reference]()
43+
- [Classes and objects]()
44+
- [Writing internal functions]()
45+
- [Zend alloc]()
46+
- [Iterators]()
47+
- [Cycle collector]()
48+
- [Closures]()
49+
- [Enums]()
50+
- [Observers]()
51+
- [ZTS]()
52+
53+
# SAPIs
54+
55+
- [Core concepts]()
56+
- [FPM]()
57+
- [CLI]()
58+
- [Builtin web server]()
59+
60+
# Extensions
61+
62+
- [Core concepts]()
63+
- [Opcache]()
64+
- [Shared memory]()
65+
- [Opcode persistence]()
66+
- [Inheritance cache]()
67+
- [JIT]()
68+
- [Tracing]()
69+
- [IR]()
70+
- [Streams]()
71+
- [DOM]()
72+
73+
# Miscellaneous
74+
75+
- [Performance profiling]()
76+
- [CI infrastructure]()
77+
- [Serialization format]()
78+
- [Old]()
79+
- [Input filter](./miscellaneous/old/input-filter.md)
80+
- [Mailing list rules](./miscellaneous/old/mailinglist-rules.md)
81+
- [Output API](./miscellaneous/old/output-api.md)
82+
- [Parameter parsing API](./miscellaneous/old/parameter-parsing-api.md)
83+
- [Release process](./miscellaneous/old/release-process.md)
84+
- [Self contained extensions](./miscellaneous/old/self-contained-extensions.md)
85+
- [Streams](./miscellaneous/old/streams.md)
86+
- [Unix build system](./miscellaneous/old/unix-build-system.md)

‎docs/src/introduction/getting-started.md

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# Getting started
2+
3+
Welcome to the php-src documentation!
4+
5+
<div class="warning">
6+
This documentation is work in progress.
7+
8+
At this point in time, there are other guides that provide a more complete picture of the PHP project. Check the
9+
[CONTRIBUTING.md](https://github.com/php/php-src/blob/master/CONTRIBUTING.md#technical-resources) file for a list of
10+
technical resources.
11+
12+
</div>
13+
14+
php-src is the canonical implementation of the interpreter for the PHP programming language, as well as various
15+
extensions that provide common functionality. This documentation is intended to help you understand how the interpreter
16+
works, how you can build and test changes, and how you can create extensions yourself.
17+
18+
This documentation is not intended to be comprehensive, but is meant to explain core concepts that are not easy to grasp
19+
by reading code alone.
20+
21+
## How to get help?
22+
23+
Getting started with a new and complicated project like php-src can be overwhelming. While there's no way around reading
24+
lots and lots of code, asking questions of somebody with experience can save a lot of time. Luckily, many core
25+
developers are eager to help. Here are some ways you can get in touch.
26+
27+
- Slack (FIXME: @Roman)
28+
- Discourse (FIXME: @Roman)
29+
- [R11 on StackOverflow](https://chat.stackoverflow.com/rooms/11/php)
30+
31+
## Prerequisites
32+
33+
The php-src interpreter is written in C, and so are most of the bundled extensions. Extensions can also be written in
34+
C++. ext-intl is currently the only bundled extension written in C++. As such, it is advisable that you have _some_
35+
knowledge of C.
36+
37+
It is also advisable to get familiar with the semantics of PHP itself, as this will help you determine correct behavior
38+
for bugs, and desireable behavior for new language features.

‎docs/input-filter.md renamed to ‎docs/src/miscellaneous/old/input-filter.md

File renamed without changes.

‎docs/mailinglist-rules.md renamed to ‎docs/src/miscellaneous/old/mailinglist-rules.md

File renamed without changes.

‎docs/output-api.md renamed to ‎docs/src/miscellaneous/old/output-api.md

File renamed without changes.

‎docs/parameter-parsing-api.md renamed to ‎docs/src/miscellaneous/old/parameter-parsing-api.md

File renamed without changes.

‎docs/release-process.md renamed to ‎docs/src/miscellaneous/old/release-process.md

File renamed without changes.

‎docs/self-contained-extensions.md renamed to ‎docs/src/miscellaneous/old/self-contained-extensions.md

File renamed without changes.

‎docs/streams.md renamed to ‎docs/src/miscellaneous/old/streams.md

File renamed without changes.

‎docs/unix-build-system.md renamed to ‎docs/src/miscellaneous/old/unix-build-system.md

File renamed without changes.

0 commit comments

Comments
 (0)