git.m6w6.name Git - awesomized/ext-ion/blob - docs/README.md

   1 # ext-ion docs
   2 https://awesomized.github.io/ext-ion
   3
   4 ## Howto update docs
   5
   6 1. Edit stub: `$EDITOR ../ion.stub.php`
   7 2. [Rebuild](#Build)
   8 3. [Review](#Review); repeat from 2. if necessary
   9 4. [Deploy](#Deployment)
  10
  11 ## Howto make a release
  12
  13 ### 1. Create tag
  14 ```
  15 git tag vX.Y.Z
  16 ```
  17
  18 ### 2. Rebuild docs
  19 See [Rebuild](#Rebuild).
  20
  21 ### 3. Review docs
  22 See [Review](#Review).
  23
  24 ### 4. Commit docs with release changelog:
  25 ```
  26 git add .
  27 git commit
  28 ```
  29 ```
  30 release vX.Y.Z
  31
  32 * Additions ...
  33 * Changes ...
  34 ```
  35 ### 5. Move tag:
  36 ```
  37 git tag -f vX.Y.Z
  38 ```
  39 ### 6. Release & [deploy](#Deployment):
  40 ```
  41 git push
  42 ```
  43
  44 ## Build
  45 ### Prerequisites without docker:
  46 * composer v2
  47 * PHP with ext-http and ext-dom but **without** ext-ion
  48
  49 ```
  50    ┌─────────┐
  51    │  BUILD  │                     ┌──────────┐
  52  ┌─┴─────────┴──────────────┐      │  SOURCE  │
  53  │  $ make #docker UID=$UID ├──►┌──┴──────────┴───────────┐
  54  └──────────────────────────┘   │ ../README.md            │
  55                                 │ ../ion.stub.php         │
  56  ┌──────────────────────────────┤ ../...                  │
  57  │                              └─────────────────────────┘
  58  │ ┌────────────────┐
  59  │ │  PROCESSED BY  │              ┌────────────┐
  60 ┌▼─┴────────────────┴───────┐      │  MARKDOWN  │
  61 │ ./vendor/bin/stub2ref     ├──►┌──┴────────────┴─────────┐
  62 └───────────────────────────┘   │ ./src/mdref.json        │
  63                                 │ ./src/ion.md            │
  64  ┌──────────────────────────────┤ ./src/ion/...           │
  65  │                              └─────────────────────────┘
  66  │ ┌────────────────┐
  67  │ │  PROCESSED BY  │              ┌────────┐
  68 ┌▼─┴────────────────┴───────┐      │  HTML  │
  69 │ ./vendor/bin/ref2html     ├──►┌──┴────────┴─────────────┐
  70 └───────────────────────────┘   │ ./docs/latest -> vX.Y/  │
  71                                 │ ./docs/vX.Y/index.html  │
  72                                 │ ./docs/vX.Y/ion/...     │
  73                                 └─────────────────────────┘
  74 ```
  75
  76 ## Review
  77 ### Caddy
  78 Run caddy to read the docs as they would appear on https://awesomized.github.io/ext-ion.
  79 ```shell
  80 caddy run
  81 ```
  82
  83 Use `$CADDY_ADDRESS` env var to customize the HTTP endpoint, e.g:
  84 ```shell
  85 CADDY_ADDRESS=localhost:8080 caddy run
  86 ```
  87
  88 Use docker, if you do not have caddy installed:
  89 ```shell
  90 docker-compose -f docker/compose.yml run -p 8080:80 caddy
  91 ```
  92 ### PHP
  93 Use PHP CLI server if you're desperate:
  94 ```shell
  95 php -S localhost:0 -r . .router.php
  96 ```
  97
  98 ## Deployment
  99 ```
 100    ┌──────────┐
 101    │  DEPLOY  │
 102 ┌──┴──────────┴─────────────┐
 103 │  $ git add .              │      ┌────────────┐
 104 │  $ git commit             │      │ GH ACTION  │
 105 │  $ git push               ├──►┌──┴────────────┴─────────┐
 106 └───────────────────────────┘   │  pages-build-deployment │
 107                                 └─┬───────────────────────┘
 108    ┌──────────────┐               │
 109    │  DEPLOYMENT  │               │
 110 ┌──┴──────────────┴───────────────▼───────────────────────┐
 111 │                                                         │
 112 │       https://awesomized.github.io/ext-ion/latest/      │
 113 │                                                         │
 114 └─────────────────────────────────────────────────────────┘
 115
 116 ```