Reorganize and improve documentation

.gitignore

@@ -1,8 +1,9 @@
 vendor
 composer.lock
-/docs/contributing.md
 /docs/index.md
-/docs/license.md
+/docs/contributing/index.md
+/docs/contributing/contributors.md
+/docs/usage/license.md
+/docs/usage/changelog.md
 /docs/api/
-/docs/changelog.md
 /resources/benchmarks/vars/vault.yml

CONTRIBUTING.md

@@ -34,14 +34,14 @@ You may look through the [GitHub issues](https://github.com/idealo/php-rdkafka-f
 
 * Make sure any new code you introduce has proper phpdoc. You may add extra usage documentation under /docs/usage
 
-See [work on the documentation](docs/try-out.md#work-on-the-documentation) locally.
+See [work on the documentation](docs/contributing/work-on-the-documentation.md) locally.
 
 ## Testing
 
 * 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. 
 
-See [run tests](docs/try-out.md#run-tests) locally.
+See [run tests](docs/contributing/run-tests.md) locally.
 
 ## Main Contributor List
 
-We maintain a list of main contributors to appreciate all the contributions.
+We maintain a list of main contributors to appreciate all the contributions.

README.md

@@ -43,6 +43,10 @@ This changes may depend on upcoming major releases of the RdKafka extension or i
 
 https://idealo.github.io/php-rdkafka-ffi/
 
+## Changelog
+
+See [Changelog](CHANGELOG.md) for details.
+
 ## Contributing
 
 We welcome all kinds of contributions. See the [Contribution guide](CONTRIBUTING.md) for more details.

composer.json

@@ -80,11 +80,11 @@
         "cs": "ecs check src tests examples resources/ffigen benchmarks --ansi",
         "cs-fix": "ecs check src tests examples resources/ffigen benchmarks --ansi --fix",
         "prepare-docs": [
-            "echo '---\ntitle: Getting started\n---\n' > docs/index.md",
-            "sed 's/docs\\/img/img/g' README.md | sed 's/LICENSE)/license.md)/g' | sed 's/CONTRIBUTING.md/contributing.md/g' >> docs/index.md",
-            "sed 's/docs\\/try-out/try-out/g' CONTRIBUTING.md > docs/contributing.md",
-            "cp CHANGELOG.md docs/changelog.md",
-            "cp LICENSE docs/license.md",
+            "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",
+            "sed 's/docs\\/contributing/./g' CONTRIBUTING.md > docs/contributing/index.md",
+            "cp CHANGELOG.md docs/usage/changelog.md",
+            "cp LICENSE docs/usage/license.md",
+            "php resources/docs/update-contributors.php",
             "dog"
         ]
     }

docker-compose.yml

@@ -78,3 +78,4 @@ services:
       - php-rdkafka-ffi
     ports:
       - 127.0.0.1:8000:8000
+    restart: on-failure

docs/.pages

@@ -1,8 +1,6 @@
-arrange:
-  - index.md
+nav:
+  - Getting Started: index.md
+  - usage
   - api
   - benchmarks.md
-  - try-out.md
-  - changelog.md
-  - contributing.md
-  - license.md
+  - contributing

docs/contributing/.pages

@@ -0,0 +1,7 @@
+nav:
+  - index.md
+  - project-overview.md
+  - run-tests.md
+  - work-on-the-documentation.md
+  - run-benchmarks.md
+  - contributors.md

docs/contributing/project-overview.md

@@ -0,0 +1,59 @@
+# Project Overview
+
+## Directory overview
+
+* __/benchmarks__ - phpbench based benchmark tests
+* __/docs__ - docs dir (markdown)
+* __/examples__ - example scripts
+* __/resources__
+    * __/benchmarks__ ansible playbooks setup and run benchmarks
+    * __/docker__
+        * __/php74-librdkafka-ffi__ - dockerfile for PHP 7.4 image with librdkafka and ffi & rdkafka ext (based
+          on [php:7.4-cli](https://hub.docker.com/_/php) )
+        * __/php80-librdkafka-ffi__ - dockerfile for PHP 8.0 image with librdkafka and ffi & rdkafka ext (based
+          on [php:8.0-rc-cli](https://hub.docker.com/_/php) )
+    * __/docs__ - scripts to build documentation site from /docs
+    * __/ffigen__ - config to build low level library bindings
+    * __/phpunit__ - bootstrap and config for phpunit tests
+    * __/test-extension__ - base dir for rdkafka ext compatibility tests
+* __/src__ - source dir
+* __/tests__ - tests dir
+
+## Docker Images for Development
+
+Build all images
+
+    docker-compose build --no-cache --pull
+
+Alternative: build the image individually
+
+    docker-compose build --no-cache --pull php74 php80
+
+Alternative: build the image individually and set optional build args (LIBRDKAFKA_VERSION default = v1.5.3, RDKAFKA_EXT_VERSION default =
+4.1.x for php74 / 5.x for php80)
+
+    docker-compose build --no-cache --pull --build-arg LIBRDKAFKA_VERSION="v1.5.3" --build-arg RDKAFKA_EXT_VERSION="4.1.1" php74
+
+Test - should show latest 7.4 version
+
+    docker-compose run php74 php -v
+
+Test - should show ```FFI``` in modules list
+
+    docker-compose run php74 php -m
+
+Test ffi librdkafka binding - should show current version of librdkafka:
+
+    docker-compose run php74 php examples/version.php
+
+Test - should show ```rdkafka``` in modules list
+
+    docker-compose run php74 php -dextension=rdkafka.so -m
+
+## References
+
+* [FFI extension](https://www.php.net/manual/en/book.ffi.php)
+* [librdkafka ^1.0](https://github.com/edenhill/librdkafka) ([docs](https://docs.confluent.io/current/clients/librdkafka/rdkafka_8h.html))
+* Confluent [Kafka](https://hub.docker.com/r/confluentinc/cp-kafka) / [Zookeeper](https://hub.docker.com/r/confluentinc/cp-zookeeper) docker
+  images
+* [phpbench lib](https://github.com/phpbench/phpbench) for benchmarking

docs/contributing/run-benchmarks.md

@@ -0,0 +1,35 @@
+# Run benchmarks
+
+Benchmarks use topic ```benchmarks```.
+
+Run Benchmarks
+
+    docker-compose down -v; \
+    docker-compose up -d kafka; \
+    docker-compose exec kafka cub kafka-ready -z zookeeper:2181 1 20; \
+    docker-compose run --rm php74 composer benchmarks-init; \
+    docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --store --tag=php74_ffi --group=ffi; \
+    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; \
+    docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --store --tag=php80_ffi --group=ffi; \
+    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; \
+    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; \
+    docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ext.json --report=default --store --tag=php74_ext --group=ext; \
+    docker-compose run --rm php80 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ext.json --report=default --store --tag=php80_ext --group=ext
+
+Show comparison for runtime average
+
+    docker-compose run --rm php74 vendor/bin/phpbench report \
+        --ref=php74_ffi \
+        --ref=php74_ffi_preload \
+        --ref=php80_ffi \
+        --ref=php80_ffi_preload \
+        --ref=php80_ffi_preload_jit \
+        --ref=php74_ext \
+        --ref=php80_ext \
+        --report=summary \
+        --config=benchmarks\report.json
+
+Run Api::init benchmark (fix vs auto detected version)
+
+    docker-compose run --rm php74 vendor/bin/phpbench run benchmarks --config=/app/benchmarks/ffi.json --report=default --group=Api
+

docs/contributing/run-tests.md

@@ -0,0 +1,44 @@
+# Run tests
+
+Tests use topics ```test*```.
+
+## Prepare
+
+Startup php & kafka
+
+    docker-compose up -d
+
+Updating Dependencies
+
+    docker-compose run --rm --no-deps php74 composer update
+
+Run tests
+
+    docker-compose run --rm php74 composer test-init
+    docker-compose run --rm php74 composer test
+
+Run tests with coverage
+
+    docker-compose run --rm php74 composer test-coverage
+
+### Run tests against RdKafka extension / PHP 7.4
+
+Updating Dependencies
+
+    docker-compose run --rm --no-deps php74 composer update -d /app/resources/test-extension --ignore-platform-reqs
+
+Run tests
+
+    docker-compose run --rm php74 composer test-extension-init
+    docker-compose run --rm php74 composer test-extension
+
+### Run tests against RdKafka extension / PHP 8.0
+
+Updating Dependencies
+
+    docker-compose run --rm --no-deps php80 composer update -d /app/resources/test-extension --ignore-platform-reqs
+
+Run tests
+
+    docker-compose run --rm php80 composer test-extension-init
+    docker-compose run --rm php80 composer test-extension

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

@@ -0,0 +1,14 @@
+# Work on the documentation
+
+Documentation is based on `markdown` and the static site is build with [mkdocs material](https://squidfunk.github.io/mkdocs-material/). The
+API documentation is generated by [dog](https://klitsche.github.io/dog/) as markdown.
+
+Serve documentation on http://localhost:8000/
+
+    docker-compose run --rm php74 composer prepare-docs
+    docker-compose up mkdocs
+
+Build static site in folder site
+
+    docker-compose run --rm php74 composer prepare-docs
+    docker-compose run --rm mkdocs build