Skip to content

Commit 05f2cc0

Browse files
dirxdirx
committed
Reorganize and improve documentation
1 parent 17b0a17 commit 05f2cc0

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

42 files changed

+2187
-1704
lines changed

‎.gitignore

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,9 @@
11
vendor
22
composer.lock
3-
/docs/contributing.md
43
/docs/index.md
5-
/docs/license.md
4+
/docs/contributing/index.md
5+
/docs/contributing/contributors.md
6+
/docs/usage/license.md
7+
/docs/usage/changelog.md
68
/docs/api/
7-
/docs/changelog.md
89
/resources/benchmarks/vars/vault.yml

‎CONTRIBUTING.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -34,14 +34,14 @@ You may look through the [GitHub issues](https://github.com/idealo/php-rdkafka-f
3434

3535
* Make sure any new code you introduce has proper phpdoc. You may add extra usage documentation under /docs/usage
3636

37-
See [work on the documentation](docs/try-out.md#work-on-the-documentation) locally.
37+
See [work on the documentation](docs/contributing/work-on-the-documentation.md) locally.
3838

3939
## Testing
4040

4141
* Make sure to write tests for any new feature and/or bug fixes. We use [phpunit](https://phpunit.readthedocs.io/en/latest/) for our testing.
4242

43-
See [run tests](docs/try-out.md#run-tests) locally.
43+
See [run tests](docs/contributing/run-tests.md) locally.
4444

4545
## Main Contributor List
4646

47-
We maintain a list of main contributors to appreciate all the contributions.
47+
We maintain a list of main contributors to appreciate all the contributions.

‎README.md

+4
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,10 @@ This changes may depend on upcoming major releases of the RdKafka extension or i
4343

4444
https://idealo.github.io/php-rdkafka-ffi/
4545

46+
## Changelog
47+
48+
See [Changelog](CHANGELOG.md) for details.
49+
4650
## Contributing
4751

4852
We welcome all kinds of contributions. See the [Contribution guide](CONTRIBUTING.md) for more details.

‎composer.json

+5-5
Original file line numberDiff line numberDiff line change
@@ -80,11 +80,11 @@
8080
"cs": "ecs check src tests examples resources/ffigen benchmarks --ansi",
8181
"cs-fix": "ecs check src tests examples resources/ffigen benchmarks --ansi --fix",
8282
"prepare-docs": [
83-
"echo '---\ntitle: Getting started\n---\n' > docs/index.md",
84-
"sed 's/docs\\/img/img/g' README.md | sed 's/LICENSE)/license.md)/g' | sed 's/CONTRIBUTING.md/contributing.md/g' >> docs/index.md",
85-
"sed 's/docs\\/try-out/try-out/g' CONTRIBUTING.md > docs/contributing.md",
86-
"cp CHANGELOG.md docs/changelog.md",
87-
"cp LICENSE docs/license.md",
83+
"sed 's/docs\\/img/img/g' README.md | sed 's/LICENSE)/usage\\\/license.md)/g' | sed 's/CONTRIBUTING.md/contributing\\\/index.md/g' | sed 's/CHANGELOG.md/usage\\/changelog.md/g' > docs/index.md",
84+
"sed 's/docs\\/contributing/./g' CONTRIBUTING.md > docs/contributing/index.md",
85+
"cp CHANGELOG.md docs/usage/changelog.md",
86+
"cp LICENSE docs/usage/license.md",
87+
"php resources/docs/update-contributors.php",
8888
"dog"
8989
]
9090
}

‎docker-compose.yml

+1
Original file line numberDiff line numberDiff line change
@@ -78,3 +78,4 @@ services:
7878
- php-rdkafka-ffi
7979
ports:
8080
- 127.0.0.1:8000:8000
81+
restart: on-failure

‎docs/.pages

+4-6
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,6 @@
1-
arrange:
2-
- index.md
1+
nav:
2+
- Getting Started: index.md
3+
- usage
34
- api
45
- benchmarks.md
5-
- try-out.md
6-
- changelog.md
7-
- contributing.md
8-
- license.md
6+
- contributing

‎docs/contributing/.pages

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
nav:
2+
- index.md
3+
- project-overview.md
4+
- run-tests.md
5+
- work-on-the-documentation.md
6+
- run-benchmarks.md
7+
- contributors.md

‎docs/contributing/project-overview.md

+59
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Project Overview
2+
3+
## Directory overview
4+
5+
* __/benchmarks__ - phpbench based benchmark tests
6+
* __/docs__ - docs dir (markdown)
7+
* __/examples__ - example scripts
8+
* __/resources__
9+
* __/benchmarks__ ansible playbooks setup and run benchmarks
10+
* __/docker__
11+
* __/php74-librdkafka-ffi__ - dockerfile for PHP 7.4 image with librdkafka and ffi & rdkafka ext (based
12+
on [php:7.4-cli](https://hub.docker.com/_/php) )
13+
* __/php80-librdkafka-ffi__ - dockerfile for PHP 8.0 image with librdkafka and ffi & rdkafka ext (based
14+
on [php:8.0-rc-cli](https://hub.docker.com/_/php) )
15+
* __/docs__ - scripts to build documentation site from /docs
16+
* __/ffigen__ - config to build low level library bindings
17+
* __/phpunit__ - bootstrap and config for phpunit tests
18+
* __/test-extension__ - base dir for rdkafka ext compatibility tests
19+
* __/src__ - source dir
20+
* __/tests__ - tests dir
21+
22+
## Docker Images for Development
23+
24+
Build all images
25+
26+
docker-compose build --no-cache --pull
27+
28+
Alternative: build the image individually
29+
30+
docker-compose build --no-cache --pull php74 php80
31+
32+
Alternative: build the image individually and set optional build args (LIBRDKAFKA_VERSION default = v1.5.3, RDKAFKA_EXT_VERSION default =
33+
4.1.x for php74 / 5.x for php80)
34+
35+
docker-compose build --no-cache --pull --build-arg LIBRDKAFKA_VERSION="v1.5.3" --build-arg RDKAFKA_EXT_VERSION="4.1.1" php74
36+
37+
Test - should show latest 7.4 version
38+
39+
docker-compose run php74 php -v
40+
41+
Test - should show ```FFI``` in modules list
42+
43+
docker-compose run php74 php -m
44+
45+
Test ffi librdkafka binding - should show current version of librdkafka:
46+
47+
docker-compose run php74 php examples/version.php
48+
49+
Test - should show ```rdkafka``` in modules list
50+
51+
docker-compose run php74 php -dextension=rdkafka.so -m
52+
53+
## References
54+
55+
* [FFI extension](https://www.php.net/manual/en/book.ffi.php)
56+
* [librdkafka ^1.0](https://github.com/edenhill/librdkafka) ([docs](https://docs.confluent.io/current/clients/librdkafka/rdkafka_8h.html))
57+
* Confluent [Kafka](https://hub.docker.com/r/confluentinc/cp-kafka) / [Zookeeper](https://hub.docker.com/r/confluentinc/cp-zookeeper) docker
58+
images
59+
* [phpbench lib](https://github.com/phpbench/phpbench) for benchmarking

‎docs/contributing/run-benchmarks.md

+35
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# Run benchmarks
2+
3+
Benchmarks use topic ```benchmarks```.
4+
5+
Run Benchmarks
6+
7+
docker-compose down -v; \
8+
docker-compose up -d kafka; \
9+
docker-compose exec kafka cub kafka-ready -z zookeeper:2181 1 20; \
10+
docker-compose run --rm php74 composer benchmarks-init; \
11+
docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --store --tag=php74_ffi --group=ffi; \
12+
docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi_preload.json --report=default --store --tag=php74_ffi_preload --group=ffi; \
13+
docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --store --tag=php80_ffi --group=ffi; \
14+
docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi_preload.json --report=default --store --tag=php80_ffi_preload --group=ffi; \
15+
docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi_jit.json --report=default --store --tag=php80_ffi_preload_jit --group=ffi; \
16+
docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ext.json --report=default --store --tag=php74_ext --group=ext; \
17+
docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ext.json --report=default --store --tag=php80_ext --group=ext
18+
19+
Show comparison for runtime average
20+
21+
docker-compose run --rm php74 vendor/bin/phpbench report \
22+
--ref=php74_ffi \
23+
--ref=php74_ffi_preload \
24+
--ref=php80_ffi \
25+
--ref=php80_ffi_preload \
26+
--ref=php80_ffi_preload_jit \
27+
--ref=php74_ext \
28+
--ref=php80_ext \
29+
--report=summary \
30+
--config=benchmarks\report.json
31+
32+
Run Api::init benchmark (fix vs auto detected version)
33+
34+
docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --group=Api
35+

‎docs/contributing/run-tests.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Run tests
2+
3+
Tests use topics ```test*```.
4+
5+
## Prepare
6+
7+
Startup php & kafka
8+
9+
docker-compose up -d
10+
11+
Updating Dependencies
12+
13+
docker-compose run --rm --no-deps php74 composer update
14+
15+
Run tests
16+
17+
docker-compose run --rm php74 composer test-init
18+
docker-compose run --rm php74 composer test
19+
20+
Run tests with coverage
21+
22+
docker-compose run --rm php74 composer test-coverage
23+
24+
### Run tests against RdKafka extension / PHP 7.4
25+
26+
Updating Dependencies
27+
28+
docker-compose run --rm --no-deps php74 composer update -d /app/resources/test-extension --ignore-platform-reqs
29+
30+
Run tests
31+
32+
docker-compose run --rm php74 composer test-extension-init
33+
docker-compose run --rm php74 composer test-extension
34+
35+
### Run tests against RdKafka extension / PHP 8.0
36+
37+
Updating Dependencies
38+
39+
docker-compose run --rm --no-deps php80 composer update -d /app/resources/test-extension --ignore-platform-reqs
40+
41+
Run tests
42+
43+
docker-compose run --rm php80 composer test-extension-init
44+
docker-compose run --rm php80 composer test-extension

‎docs/contributing/work-on-the-documentation.md

+14
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
# Work on the documentation
2+
3+
Documentation is based on `markdown` and the static site is build with [mkdocs material](https://squidfunk.github.io/mkdocs-material/). The
4+
API documentation is generated by [dog](https://klitsche.github.io/dog/) as markdown.
5+
6+
Serve documentation on http://localhost:8000/
7+
8+
docker-compose run --rm php74 composer prepare-docs
9+
docker-compose up mkdocs
10+
11+
Build static site in folder site
12+
13+
docker-compose run --rm php74 composer prepare-docs
14+
docker-compose run --rm mkdocs build

‎docs/img/php-rdkafka.svg

+1-1
Loading

0 commit comments

Comments
 (0)