From c6ddde0ecf409dbefef9686d24cbf66240f25578 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Thu, 6 May 2021 10:44:12 +0200 Subject: [PATCH 1/6] Replace benchmark results with link to benchmarks on landing page --- docs/best-practices/deployment.md | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/docs/best-practices/deployment.md b/docs/best-practices/deployment.md index ba9c85c..74ff1e7 100644 --- a/docs/best-practices/deployment.md +++ b/docs/best-practices/deployment.md @@ -52,23 +52,8 @@ Hello wörld! ``` You may be wondering how fast a pure PHP web server implementation could possibly be. - -``` -$ ab -n10000 -c10 http://localhost:8080/ -… -Concurrency Level: 10 -Time taken for tests: 0.991 seconds -Complete requests: 10000 -Failed requests: 0 -Total transferred: 1090000 bytes -HTML transferred: 130000 bytes -Requests per second: 10095.17 [#/sec] (mean) -Time per request: 0.991 [ms] (mean) -Time per request: 0.099 [ms] (mean, across all concurrent requests) -Transfer rate: 1074.58 [Kbytes/sec] received -``` - -The answer: Very fast! +In fact, in benchmarks this setup outperforms any traditional PHP stack by orders of magnitude. +The answer: [Lightning fast!](https://framework-x.clue.engineering/#lightning-fast) If you're going to use this in production, we still recommend running this behind a reverse proxy such as nginx, HAproxy, etc. for TLS termination From d73dff3b320f9aceb6e5edfc9ed3710d611ae91e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Fri, 7 May 2021 08:16:12 +0200 Subject: [PATCH 2/6] Add documentation about documentation (how meta) --- README.md | 30 +++++------------------------- docs/README.md | 42 ++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 25 deletions(-) create mode 100644 docs/README.md diff --git a/README.md b/README.md index a9b58d7..9fb3fb3 100644 --- a/README.md +++ b/README.md @@ -77,31 +77,11 @@ Hello wörld! ## Documentation Hooked? -See [full documentation](docs/) for more details. - -> We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to -> render our documentation to a pretty HTML version. -> -> If you want to contribute to the documentation, it's easiest to just run -> this in a Docker container like this: -> -> ```bash -> $ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material -> ``` -> -> You can access the documentation via `http://localhost:8000`. -> If you want to generate a static HTML folder for deployment, you can again -> use a Docker container like this: -> -> ```bash -> $ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build -> ``` -> -> The resulting `build/docs/` should then be deployed behind a web server (tbd). -> If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](mkdocs.yml) -> file contains an up-to-date list of all pages. -> -> Happy hacking! +See [website](https://framework-x.clue.engineering/) for full documentation. + +Found a typo or want to contribute? +The website documentation is build from the source documentation files in +the [docs/](docs/) folder. ## Tests diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..48f6bb6 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,42 @@ +# Framework X documentation + +This folder contains the source documentation files for Framework X. + +You can see the [website](https://framework-x.clue.engineering/) for the +user-accessible version. + +## Contribute + +Found a typo or want to contribute? +This folder contains everything you need to help out with the documentation. + +We use [mkdocs-material](https://squidfunk.github.io/mkdocs-material/) to +render our documentation to a pretty HTML version. + +If you want to contribute to the documentation, it's easiest to just run +this in a Docker container in the project root directory like this: + +```bash +$ docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material +``` + +You can access the documentation via `http://localhost:8000`. +Props to mkdocs, this uses live reloading, so that every change you do while +this Docker container is running should immediately be reflected in your web +browser. + +If you want to generate a static HTML folder for deployment, you can again +use a Docker container in the project root directory like this: + +```bash +$ docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material build +``` + +The resulting `build/docs/` should then be deployed behind a web server. +See also the [Framework X website repository](https://github.com/clue/framework-x-website) +for more details about the website itself. + +If you want to add a new documentation file and/or change the page order, make sure the [`mkdocs.yml`](../mkdocs.yml) +file in the project root directory contains an up-to-date list of all pages. + +Happy hacking! From 3f86f11656520840a4c20d62651719ec042868f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Fri, 7 May 2021 08:17:13 +0200 Subject: [PATCH 3/6] Exclude documentation from release archives --- .gitattributes | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitattributes b/.gitattributes index da20d18..9709aa5 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,7 +1,9 @@ /.gitattributes export-ignore /.github/workflows/ export-ignore /.gitignore export-ignore +/docs/ export-ignore /examples/ export-ignore +/mkdocs.yml export-ignore /phpunit.xml.dist export-ignore /phpunit.xml.legacy export-ignore /tests/ export-ignore From 8f7c0ecf93d4f0e13822426fa2a9410bab680d6e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Fri, 7 May 2021 08:41:54 +0200 Subject: [PATCH 4/6] More consistent quickstart example throughout documentation --- README.md | 59 +++++++++++++++++------------- docs/getting-started/quickstart.md | 8 ++++ 2 files changed, 42 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 9fb3fb3..f84ec5e 100644 --- a/README.md +++ b/README.md @@ -11,27 +11,10 @@ Framework X – the simple and fast micro framework for building reactive web ap ## Quickstart -First manually change your `composer.json` to include these lines: - -```json -{ - "repositories": [ - { - "type": "vcs", - "url": "https://github.com/clue-access/framework-x" - } - ] -} -``` - -Simply install Framework X: - -```bash -$ composer require clue/framework-x:dev-main -``` - -Once everything is installed, you can now use this example to get started with -a new `app.php` file: +Start by creating an empty project directory. +Next, we can start by taking a look at a simple example application. +You can use this example to get started by creating a new `app.php` file in your +empty project directory: ```php get('/', function () { ); }); +$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) { + return new React\Http\Message\Response( + 200, + [], + "Hello " . $request->getAttribute('name') . "!\n" + ); +}); + +$app->run(); $loop->run(); ``` +Next, we need to install X and its dependencies to actually run this project. +Start by creating a new `composer.json` in the project directory with the following contents: + +```json +{ + "repositories": [ + { + "type": "vcs", + "url": "https://github.com/clue-access/framework-x" + } + ] +} +``` + +Finally, simply install Framework X: + +```bash +$ composer require clue/framework-x:dev-main +``` + That's it already! The next step is now to serve this web application. One of the nice properties of this project is that is works both behind traditional web server setups as well as in a stand-alone environment. @@ -67,10 +79,7 @@ You can now use your favorite webbrowser or command line tool to check your web application responds as expected: ```bash -$ curl -v http://localhost:8080/ -HTTP/1.1 200 OK -… - +$ curl http://localhost:8080/ Hello wörld! ``` diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md index 421e808..53faa1c 100644 --- a/docs/getting-started/quickstart.md +++ b/docs/getting-started/quickstart.md @@ -33,6 +33,14 @@ $app->get('/', function () { ); }); +$app->get('/users/{name}', function (Psr\Http\Message\ServerRequestInterface $request) { + return new React\Http\Message\Response( + 200, + [], + "Hello " . $request->getAttribute('name') . "!\n" + ); +}); + $app->run(); $loop->run(); ``` From e436b263d3e503f83857a0a851564cea319e6c16 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Fri, 7 May 2021 08:51:09 +0200 Subject: [PATCH 5/6] Add link to GitHub in all documentation pages --- mkdocs.yml | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/mkdocs.yml b/mkdocs.yml index 4dbb56f..b077df2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -3,10 +3,16 @@ site_dir: build/docs extra: homepage: ../ +repo_url: https://github.com/clue/framework-x +repo_name: clue/framework-x +edit_uri: "" # not publicly accessible while in early access + theme: name: material features: - navigation.sections + icon: + repo: fontawesome/brands/github markdown_extensions: - pymdownx.highlight From 2f73e1cfacbbe331c2234394c5f7f7ac98f51c38 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Christian=20L=C3=BCck?= Date: Fri, 7 May 2021 09:05:01 +0200 Subject: [PATCH 6/6] Configure site_url for documentation to fix sitemap URLs --- mkdocs.yml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/mkdocs.yml b/mkdocs.yml index b077df2..a7d595a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -1,4 +1,5 @@ -site_name: Documentation +site_name: Framework X documentation +site_url: https://framework-x.clue.engineering/docs/ site_dir: build/docs extra: homepage: ../