diff --git a/.github/render-documentation.sh b/.github/render-documentation.sh index fc10ea81..d74a2d4f 100755 --- a/.github/render-documentation.sh +++ b/.github/render-documentation.sh @@ -5,6 +5,6 @@ DIR="$(dirname $(realpath "$0"))" echo $DIR export STORK_VERSION=$(cat "$DIR/project.yml" | yq eval '.release.current-version' -) - +cd docs mike deploy --push --update-aliases $STORK_VERSION latest --branch gh-pages mike set-default --push latest \ No newline at end of file diff --git a/.github/workflows/website.yml b/.github/workflows/website.yml index acf73785..fd22da26 100644 --- a/.github/workflows/website.yml +++ b/.github/workflows/website.yml @@ -28,11 +28,10 @@ jobs: run: | git config --global user.name "SmallRye CI" git config --global user.email "smallrye@googlegroups.com" + cd docs sudo snap install yq - pip install mkdocs-material - pip install mkdocs-macros-plugin - pip install mkdocs-build-plantuml-plugin - pip install mike + pip install + cd .. - name: Build local artifacts run: mvn -B install -DskipTests - name: Render docs and publish diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 785d7bdb..591c7006 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -56,39 +56,42 @@ Wait for a bit, and you're done. ## Building the documentation -The documentation is built using [MKDoc](https://www.mkdocs.org/). +The documentation is built using [MKDoc](https://www.mkdocs.org/) and it stored in the `docs` directory ### Prerequisites -You need Python 3 installed on your machine, with the following modules: +You need Python 3 installed on your machine, as well as _pipenv_: ```shell -pip3 install mkdocs -pip3 install mkdocs-material -pip3 install mkdocs-macros-plugin -pip3 install mkdocs-build-plantuml-plugin -pip3 install mike +# From the `docs` directory +pip3 install pipenv # if you don't have it yet +pipenv install ``` ### Structure -The website configuration is in the `mkdocs.yml` file. +The website configuration is in the `docs/mkdocs.yml` file. The content is in the `docs` module. ### Build -You can build the web site using, from the project root: +You can build the web site using, from the `docs` module: ```shell -mkdocs build +pipenv run mkdocs build ``` The website is generated in the `site` directory. +You can also enable the _serve_ mode, which update the website while you update it: -You can also enable the _serve_ mode, which update the web site while you update it: +```shell +pipenv run mkdocs serve +``` + +### Upgrade the dependencies ```shell -mkdocs serve +pipenv update ``` ### Deployment diff --git a/docs/Pipfile b/docs/Pipfile new file mode 100644 index 00000000..ba853ed6 --- /dev/null +++ b/docs/Pipfile @@ -0,0 +1,16 @@ +[[source]] +url = "https://pypi.org/simple" +verify_ssl = true +name = "pypi" + +[packages] +mkdocs = "*" +mkdocs-material = "*" +mkdocs-macros-plugin = "*" +mkdocs-build-plantuml-plugin = "*" +mike = "*" + +[dev-packages] + +[requires] +python_version = "3" diff --git a/docs/Pipfile.lock b/docs/Pipfile.lock new file mode 100644 index 00000000..15fce729 --- /dev/null +++ b/docs/Pipfile.lock @@ -0,0 +1,317 @@ +{ + "_meta": { + "hash": { + "sha256": "b2a1dfd265d14d43c51f066a1ebc1b4a37830c21b68742e9fdd2b0bf24c134cd" + }, + "pipfile-spec": 6, + "requires": { + "python_version": "3" + }, + "sources": [ + { + "name": "pypi", + "url": "https://pypi.org/simple", + "verify_ssl": true + } + ] + }, + "default": { + "click": { + "hashes": [ + "sha256:7682dc8afb30297001674575ea00d1814d808d6a36af415a82bd481d37ba7b8e", + "sha256:bb4d8133cb15a609f44e8213d9b391b0809795062913b383c62be0ee95b1db48" + ], + "markers": "python_version >= '3.7'", + "version": "==8.1.3" + }, + "ghp-import": { + "hashes": [ + "sha256:8337dd7b50877f163d4c0289bc1f1c7f127550241988d568c1db512c4324a619", + "sha256:9c535c4c61193c2df8871222567d7fd7e5014d835f97dc7b7439069e2413d343" + ], + "version": "==2.1.0" + }, + "httplib2": { + "hashes": [ + "sha256:58a98e45b4b1a48273073f905d2961666ecf0fbac4250ea5b47aef259eb5c585", + "sha256:8b6a905cb1c79eefd03f8669fd993c36dc341f7c558f056cb5a33b5c2f458543" + ], + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", + "version": "==0.20.4" + }, + "importlib-metadata": { + "hashes": [ + "sha256:637245b8bab2b6502fcbc752cc4b7a6f6243bb02b31c5c26156ad103d3d45670", + "sha256:7401a975809ea1fdc658c3aa4f78cc2195a0e019c5cbc4c06122884e9ae80c23" + ], + "markers": "python_version >= '3.7'", + "version": "==4.12.0" + }, + "jinja2": { + "hashes": [ + "sha256:31351a702a408a9e7595a8fc6150fc3f43bb6bf7e319770cbc0db9df9437e852", + "sha256:6088930bfe239f0e6710546ab9c19c9ef35e29792895fed6e6e31a023a182a61" + ], + "markers": "python_version >= '3.7'", + "version": "==3.1.2" + }, + "markdown": { + "hashes": [ + "sha256:cbb516f16218e643d8e0a95b309f77eb118cb138d39a4f27851e6a63581db874", + "sha256:f5da449a6e1c989a4cea2631aa8ee67caa5a2ef855d551c88f9e309f4634c621" + ], + "markers": "python_version >= '3.6'", + "version": "==3.3.7" + }, + "markupsafe": { + "hashes": [ + "sha256:0212a68688482dc52b2d45013df70d169f542b7394fc744c02a57374a4207003", + "sha256:089cf3dbf0cd6c100f02945abeb18484bd1ee57a079aefd52cffd17fba910b88", + "sha256:10c1bfff05d95783da83491be968e8fe789263689c02724e0c691933c52994f5", + "sha256:33b74d289bd2f5e527beadcaa3f401e0df0a89927c1559c8566c066fa4248ab7", + "sha256:3799351e2336dc91ea70b034983ee71cf2f9533cdff7c14c90ea126bfd95d65a", + "sha256:3ce11ee3f23f79dbd06fb3d63e2f6af7b12db1d46932fe7bd8afa259a5996603", + "sha256:421be9fbf0ffe9ffd7a378aafebbf6f4602d564d34be190fc19a193232fd12b1", + "sha256:43093fb83d8343aac0b1baa75516da6092f58f41200907ef92448ecab8825135", + "sha256:46d00d6cfecdde84d40e572d63735ef81423ad31184100411e6e3388d405e247", + "sha256:4a33dea2b688b3190ee12bd7cfa29d39c9ed176bda40bfa11099a3ce5d3a7ac6", + "sha256:4b9fe39a2ccc108a4accc2676e77da025ce383c108593d65cc909add5c3bd601", + "sha256:56442863ed2b06d19c37f94d999035e15ee982988920e12a5b4ba29b62ad1f77", + "sha256:671cd1187ed5e62818414afe79ed29da836dde67166a9fac6d435873c44fdd02", + "sha256:694deca8d702d5db21ec83983ce0bb4b26a578e71fbdbd4fdcd387daa90e4d5e", + "sha256:6a074d34ee7a5ce3effbc526b7083ec9731bb3cbf921bbe1d3005d4d2bdb3a63", + "sha256:6d0072fea50feec76a4c418096652f2c3238eaa014b2f94aeb1d56a66b41403f", + "sha256:6fbf47b5d3728c6aea2abb0589b5d30459e369baa772e0f37a0320185e87c980", + "sha256:7f91197cc9e48f989d12e4e6fbc46495c446636dfc81b9ccf50bb0ec74b91d4b", + "sha256:86b1f75c4e7c2ac2ccdaec2b9022845dbb81880ca318bb7a0a01fbf7813e3812", + "sha256:8dc1c72a69aa7e082593c4a203dcf94ddb74bb5c8a731e4e1eb68d031e8498ff", + "sha256:8e3dcf21f367459434c18e71b2a9532d96547aef8a871872a5bd69a715c15f96", + "sha256:8e576a51ad59e4bfaac456023a78f6b5e6e7651dcd383bcc3e18d06f9b55d6d1", + "sha256:96e37a3dc86e80bf81758c152fe66dbf60ed5eca3d26305edf01892257049925", + "sha256:97a68e6ada378df82bc9f16b800ab77cbf4b2fada0081794318520138c088e4a", + "sha256:99a2a507ed3ac881b975a2976d59f38c19386d128e7a9a18b7df6fff1fd4c1d6", + "sha256:a49907dd8420c5685cfa064a1335b6754b74541bbb3706c259c02ed65b644b3e", + "sha256:b09bf97215625a311f669476f44b8b318b075847b49316d3e28c08e41a7a573f", + "sha256:b7bd98b796e2b6553da7225aeb61f447f80a1ca64f41d83612e6139ca5213aa4", + "sha256:b87db4360013327109564f0e591bd2a3b318547bcef31b468a92ee504d07ae4f", + "sha256:bcb3ed405ed3222f9904899563d6fc492ff75cce56cba05e32eff40e6acbeaa3", + "sha256:d4306c36ca495956b6d568d276ac11fdd9c30a36f1b6eb928070dc5360b22e1c", + "sha256:d5ee4f386140395a2c818d149221149c54849dfcfcb9f1debfe07a8b8bd63f9a", + "sha256:dda30ba7e87fbbb7eab1ec9f58678558fd9a6b8b853530e176eabd064da81417", + "sha256:e04e26803c9c3851c931eac40c695602c6295b8d432cbe78609649ad9bd2da8a", + "sha256:e1c0b87e09fa55a220f058d1d49d3fb8df88fbfab58558f1198e08c1e1de842a", + "sha256:e72591e9ecd94d7feb70c1cbd7be7b3ebea3f548870aa91e2732960fa4d57a37", + "sha256:e8c843bbcda3a2f1e3c2ab25913c80a3c5376cd00c6e8c4a86a89a28c8dc5452", + "sha256:efc1913fd2ca4f334418481c7e595c00aad186563bbc1ec76067848c7ca0a933", + "sha256:f121a1420d4e173a5d96e47e9a0c0dcff965afdf1626d28de1460815f7c4ee7a", + "sha256:fc7b548b17d238737688817ab67deebb30e8073c95749d55538ed473130ec0c7" + ], + "markers": "python_version >= '3.7'", + "version": "==2.1.1" + }, + "mergedeep": { + "hashes": [ + "sha256:0096d52e9dad9939c3d975a774666af186eda617e6ca84df4c94dec30004f2a8", + "sha256:70775750742b25c0d8f36c55aed03d24c3384d17c951b3175d898bd778ef0307" + ], + "markers": "python_version >= '3.6'", + "version": "==1.3.4" + }, + "mike": { + "hashes": [ + "sha256:4c307c28769834d78df10f834f57f810f04ca27d248f80a75f49c6fa2d1527ca", + "sha256:56c3f1794c2d0b5fdccfa9b9487beb013ca813de2e3ad0744724e9d34d40b77b" + ], + "index": "pypi", + "version": "==1.1.2" + }, + "mkdocs": { + "hashes": [ + "sha256:a41a2ff25ce3bbacc953f9844ba07d106233cd76c88bac1f59cb1564ac0d87ed", + "sha256:fda92466393127d2da830bc6edc3a625a14b436316d1caf347690648e774c4f0" + ], + "index": "pypi", + "version": "==1.3.1" + }, + "mkdocs-build-plantuml-plugin": { + "hashes": [ + "sha256:0656d447b8af66c0b290c51c1764a6a5b16c12c4226db3345ac6966c21819815", + "sha256:6ba7a5f12eaad61c9ad7595413a92511c450fb6fbc341fd214bd2b1b4d45b1c8" + ], + "index": "pypi", + "version": "==1.7.4" + }, + "mkdocs-macros-plugin": { + "hashes": [ + "sha256:96bdabeb98b96139544f0048ea2f5cb80c7befde6b21e94c6d4596c22774cbcf", + "sha256:9e64e1cabcf6925359de29fe54f62d5847fb455c2528c440b87f8f1240650608" + ], + "index": "pypi", + "version": "==0.7.0" + }, + "mkdocs-material": { + "hashes": [ + "sha256:263f2721f3abe533b61f7c8bed435a0462620912742c919821ac2d698b4bfe67", + "sha256:dc82b667d2a83f0de581b46a6d0949732ab77e7638b87ea35b770b33bc02e75a" + ], + "index": "pypi", + "version": "==8.3.9" + }, + "mkdocs-material-extensions": { + "hashes": [ + "sha256:a82b70e533ce060b2a5d9eb2bc2e1be201cf61f901f93704b4acf6e3d5983a44", + "sha256:bfd24dfdef7b41c312ede42648f9eb83476ea168ec163b613f9abd12bbfddba2" + ], + "markers": "python_version >= '3.6'", + "version": "==1.0.3" + }, + "packaging": { + "hashes": [ + "sha256:dd47c42927d89ab911e606518907cc2d3a1f38bbd026385970643f9c5b8ecfeb", + "sha256:ef103e05f519cdc783ae24ea4e2e0f508a9c99b2d4969652eed6a2e1ea5bd522" + ], + "markers": "python_version >= '3.6'", + "version": "==21.3" + }, + "pygments": { + "hashes": [ + "sha256:5eb116118f9612ff1ee89ac96437bb6b49e8f04d8a13b514ba26f620208e26eb", + "sha256:dc9c10fb40944260f6ed4c688ece0cd2048414940f1cea51b8b226318411c519" + ], + "markers": "python_version >= '3.6'", + "version": "==2.12.0" + }, + "pymdown-extensions": { + "hashes": [ + "sha256:3ef2d998c0d5fa7eb09291926d90d69391283561cf6306f85cd588a5eb5befa0", + "sha256:ec141c0f4983755349f0c8710416348d1a13753976c028186ed14f190c8061c4" + ], + "markers": "python_version >= '3.7'", + "version": "==9.5" + }, + "pyparsing": { + "hashes": [ + "sha256:2b020ecf7d21b687f219b71ecad3631f644a47f01403fa1d1036b0c6416d70fb", + "sha256:5026bae9a10eeaefb61dab2f09052b9f4307d44aee4eda64b309723d8d206bbc" + ], + "markers": "python_full_version >= '3.6.8'", + "version": "==3.0.9" + }, + "python-dateutil": { + "hashes": [ + "sha256:0123cacc1627ae19ddf3c27a5de5bd67ee4586fbdd6440d9748f8abb483d3e86", + "sha256:961d03dc3453ebbc59dbdea9e4e11c5651520a876d0f4db161e8674aae935da9" + ], + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", + "version": "==2.8.2" + }, + "pyyaml": { + "hashes": [ + "sha256:0283c35a6a9fbf047493e3a0ce8d79ef5030852c51e9d911a27badfde0605293", + "sha256:055d937d65826939cb044fc8c9b08889e8c743fdc6a32b33e2390f66013e449b", + "sha256:07751360502caac1c067a8132d150cf3d61339af5691fe9e87803040dbc5db57", + "sha256:0b4624f379dab24d3725ffde76559cff63d9ec94e1736b556dacdfebe5ab6d4b", + "sha256:0ce82d761c532fe4ec3f87fc45688bdd3a4c1dc5e0b4a19814b9009a29baefd4", + "sha256:1e4747bc279b4f613a09eb64bba2ba602d8a6664c6ce6396a4d0cd413a50ce07", + "sha256:213c60cd50106436cc818accf5baa1aba61c0189ff610f64f4a3e8c6726218ba", + "sha256:231710d57adfd809ef5d34183b8ed1eeae3f76459c18fb4a0b373ad56bedcdd9", + "sha256:277a0ef2981ca40581a47093e9e2d13b3f1fbbeffae064c1d21bfceba2030287", + "sha256:2cd5df3de48857ed0544b34e2d40e9fac445930039f3cfe4bcc592a1f836d513", + "sha256:40527857252b61eacd1d9af500c3337ba8deb8fc298940291486c465c8b46ec0", + "sha256:473f9edb243cb1935ab5a084eb238d842fb8f404ed2193a915d1784b5a6b5fc0", + "sha256:48c346915c114f5fdb3ead70312bd042a953a8ce5c7106d5bfb1a5254e47da92", + "sha256:50602afada6d6cbfad699b0c7bb50d5ccffa7e46a3d738092afddc1f9758427f", + "sha256:68fb519c14306fec9720a2a5b45bc9f0c8d1b9c72adf45c37baedfcd949c35a2", + "sha256:77f396e6ef4c73fdc33a9157446466f1cff553d979bd00ecb64385760c6babdc", + "sha256:819b3830a1543db06c4d4b865e70ded25be52a2e0631ccd2f6a47a2822f2fd7c", + "sha256:897b80890765f037df3403d22bab41627ca8811ae55e9a722fd0392850ec4d86", + "sha256:98c4d36e99714e55cfbaaee6dd5badbc9a1ec339ebfc3b1f52e293aee6bb71a4", + "sha256:9df7ed3b3d2e0ecfe09e14741b857df43adb5a3ddadc919a2d94fbdf78fea53c", + "sha256:9fa600030013c4de8165339db93d182b9431076eb98eb40ee068700c9c813e34", + "sha256:a80a78046a72361de73f8f395f1f1e49f956c6be882eed58505a15f3e430962b", + "sha256:b3d267842bf12586ba6c734f89d1f5b871df0273157918b0ccefa29deb05c21c", + "sha256:b5b9eccad747aabaaffbc6064800670f0c297e52c12754eb1d976c57e4f74dcb", + "sha256:c5687b8d43cf58545ade1fe3e055f70eac7a5a1a0bf42824308d868289a95737", + "sha256:cba8c411ef271aa037d7357a2bc8f9ee8b58b9965831d9e51baf703280dc73d3", + "sha256:d15a181d1ecd0d4270dc32edb46f7cb7733c7c508857278d3d378d14d606db2d", + "sha256:d4db7c7aef085872ef65a8fd7d6d09a14ae91f691dec3e87ee5ee0539d516f53", + "sha256:d4eccecf9adf6fbcc6861a38015c2a64f38b9d94838ac1810a9023a0609e1b78", + "sha256:d67d839ede4ed1b28a4e8909735fc992a923cdb84e618544973d7dfc71540803", + "sha256:daf496c58a8c52083df09b80c860005194014c3698698d1a57cbcfa182142a3a", + "sha256:e61ceaab6f49fb8bdfaa0f92c4b57bcfbea54c09277b1b4f7ac376bfb7a7c174", + "sha256:f84fbc98b019fef2ee9a1cb3ce93e3187a6df0b2538a651bfb890254ba9f90b5" + ], + "markers": "python_version >= '3.6'", + "version": "==6.0" + }, + "pyyaml-env-tag": { + "hashes": [ + "sha256:70092675bda14fdec33b31ba77e7543de9ddc88f2e5b99160396572d11525bdb", + "sha256:af31106dec8a4d68c60207c1886031cbf839b68aa7abccdb19868200532c2069" + ], + "markers": "python_version >= '3.6'", + "version": "==0.1" + }, + "six": { + "hashes": [ + "sha256:1e61c37477a1626458e36f7b1d82aa5c9b094fa4802892072e49de9c60c4c926", + "sha256:8abb2f1d86890a2dfb989f9a77cfcfd3e47c2a354b01111771326f8aa26e0254" + ], + "markers": "python_version >= '2.7' and python_version not in '3.0, 3.1, 3.2, 3.3'", + "version": "==1.16.0" + }, + "termcolor": { + "hashes": [ + "sha256:1d6d69ce66211143803fbc56652b41d73b4a400a2891d7bf7a1cdf4c02de613b" + ], + "version": "==1.1.0" + }, + "verspec": { + "hashes": [ + "sha256:741877d5633cc9464c45a469ae2a31e801e6dbbaa85b9675d481cda100f11c31", + "sha256:c4504ca697b2056cdb4bfa7121461f5a0e81809255b41c03dda4ba823637c01e" + ], + "version": "==0.1.0" + }, + "watchdog": { + "hashes": [ + "sha256:083171652584e1b8829581f965b9b7723ca5f9a2cd7e20271edf264cfd7c1412", + "sha256:117ffc6ec261639a0209a3252546b12800670d4bf5f84fbd355957a0595fe654", + "sha256:186f6c55abc5e03872ae14c2f294a153ec7292f807af99f57611acc8caa75306", + "sha256:195fc70c6e41237362ba720e9aaf394f8178bfc7fa68207f112d108edef1af33", + "sha256:226b3c6c468ce72051a4c15a4cc2ef317c32590d82ba0b330403cafd98a62cfd", + "sha256:247dcf1df956daa24828bfea5a138d0e7a7c98b1a47cf1fa5b0c3c16241fcbb7", + "sha256:255bb5758f7e89b1a13c05a5bceccec2219f8995a3a4c4d6968fe1de6a3b2892", + "sha256:43ce20ebb36a51f21fa376f76d1d4692452b2527ccd601950d69ed36b9e21609", + "sha256:4f4e1c4aa54fb86316a62a87b3378c025e228178d55481d30d857c6c438897d6", + "sha256:5952135968519e2447a01875a6f5fc8c03190b24d14ee52b0f4b1682259520b1", + "sha256:64a27aed691408a6abd83394b38503e8176f69031ca25d64131d8d640a307591", + "sha256:6b17d302850c8d412784d9246cfe8d7e3af6bcd45f958abb2d08a6f8bedf695d", + "sha256:70af927aa1613ded6a68089a9262a009fbdf819f46d09c1a908d4b36e1ba2b2d", + "sha256:7a833211f49143c3d336729b0020ffd1274078e94b0ae42e22f596999f50279c", + "sha256:8250546a98388cbc00c3ee3cc5cf96799b5a595270dfcfa855491a64b86ef8c3", + "sha256:97f9752208f5154e9e7b76acc8c4f5a58801b338de2af14e7e181ee3b28a5d39", + "sha256:9f05a5f7c12452f6a27203f76779ae3f46fa30f1dd833037ea8cbc2887c60213", + "sha256:a735a990a1095f75ca4f36ea2ef2752c99e6ee997c46b0de507ba40a09bf7330", + "sha256:ad576a565260d8f99d97f2e64b0f97a48228317095908568a9d5c786c829d428", + "sha256:b530ae007a5f5d50b7fbba96634c7ee21abec70dc3e7f0233339c81943848dc1", + "sha256:bfc4d351e6348d6ec51df007432e6fe80adb53fd41183716017026af03427846", + "sha256:d3dda00aca282b26194bdd0adec21e4c21e916956d972369359ba63ade616153", + "sha256:d9820fe47c20c13e3c9dd544d3706a2a26c02b2b43c993b62fcd8011bcc0adb3", + "sha256:ed80a1628cee19f5cfc6bb74e173f1b4189eb532e705e2a13e3250312a62e0c9", + "sha256:ee3e38a6cc050a8830089f79cbec8a3878ec2fe5160cdb2dc8ccb6def8552658" + ], + "markers": "python_version >= '3.6'", + "version": "==2.1.9" + }, + "zipp": { + "hashes": [ + "sha256:05b45f1ee8f807d0cc928485ca40a07cb491cf092ff587c0df9cb1fd154848d2", + "sha256:47c40d7fe183a6f21403a199b3e4192cca5774656965b0a4988ad2f8feb5f009" + ], + "markers": "python_version >= '3.7'", + "version": "==3.8.1" + } + }, + "develop": {} +} diff --git a/docs/concepts.md b/docs/docs/concepts.md similarity index 87% rename from docs/concepts.md rename to docs/docs/concepts.md index 0bff68ec..8952b73c 100644 --- a/docs/concepts.md +++ b/docs/docs/concepts.md @@ -4,7 +4,9 @@ This page presents the concepts used in Stork. When using Stork in a _managed_ environment, such as Quarkus, all these concepts are hidden, as you only configure the lookup and selection. However, when using the programmatic API, you will use these concepts directly. -![concepts](target/stork.png) + +![concepts](target/stork.svg#only-light) +![concepts](target/stork_dark.svg#only-dark) ## Process overview @@ -14,7 +16,8 @@ When using the programmatic API of Stork, you can: 2. Retrieve the `Service` you want to use. Each `Service` is associated with a name. 3. Retrieve the `ServiceInstance` which will provide the metadata to access the actual service. -![concepts](target/sequence.png) +![service discovery and selection](target/sequence.svg#only-light) +![service discovery and selection](target/sequence_dark.svg#only-dark) Behind the scenes, Stork will handle the service lookup and selection. @@ -30,7 +33,7 @@ The `Stork` instance is a _singleton_. It needs to be initialized once (when the application starts) and shutdown when the application stops: ```java linenums="1" ---8<-- "docs/snippets/examples/StorkEntryPointExample.java" +--8<-- "snippets/examples/StorkEntryPointExample.java" ``` During the initialization, Stork looks for `io.smallrye.stork.config.ConfigProvider` SPI provider and retrieves the list of managed services: @@ -46,7 +49,7 @@ Services are pre-configured with their name, service discovery, and optionally, You retrieve a `Service` using the `Stork#getService(String name)` method. ```java linenums="1" ---8<-- "docs/snippets/examples/StorkServiceExample.java" +--8<-- "snippets/examples/StorkServiceExample.java" ``` The `Service` lets you retrieve the list of `ServiceInstance`, or select a single one, when a load-balancer is configured. @@ -57,7 +60,7 @@ The `io.smallrye.stork.api.ServiceInstance` represents an actual instance of the It provides the metadata to configure a _client_ to interact with that specific instance of service. ```java linenums="1" ---8<-- "docs/snippets/examples/StorkServiceLookupExample.java" +--8<-- "snippets/examples/StorkServiceLookupExample.java" ``` The service selection is a two-steps process: @@ -66,7 +69,7 @@ The service selection is a two-steps process: 2. Service selection - using the load balancer ```java linenums="1" ---8<-- "docs/snippets/examples/StorkServiceSelectionExample.java" +--8<-- "snippets/examples/StorkServiceSelectionExample.java" ``` ## Service Discovery diff --git a/docs/docs/diagrams/includes/themes/dark.puml b/docs/docs/diagrams/includes/themes/dark.puml new file mode 100644 index 00000000..bb4b2ef1 --- /dev/null +++ b/docs/docs/diagrams/includes/themes/dark.puml @@ -0,0 +1,10 @@ +!define BG_MAIN_COLOR #1A618C +!define BG_SECONDARY_COLOR #616768 +!define BG_PACKAGE_COLOR #7a209f +!define BORDER_COLOR #EEEEEE +!define FONT_COLOR #EEEEEE +!define ARROW_COLOR #EEEEEE + +' include the general skinparams for both, light and dark +' to overwrite with the given settings +!include general.puml \ No newline at end of file diff --git a/docs/docs/diagrams/includes/themes/general.puml b/docs/docs/diagrams/includes/themes/general.puml new file mode 100644 index 00000000..f041d34d --- /dev/null +++ b/docs/docs/diagrams/includes/themes/general.puml @@ -0,0 +1,98 @@ +!define BORDER_THICKNESS 3 +skinparam backgroundColor transparent + +skinparam classFontSize 30 + +skinparam Padding 4 +skinparam RoundCorner 4 +skinparam Shadowing false + +skinparam Default { + FontColor FONT_COLOR + FontSize 30 +} + +skinparam class { + BackgroundColor BG_MAIN_COLOR + ArrowColor FONT_COLOR + BorderColor FONT_COLOR + FontSize 30 +} + +skinparam Arrow { + Color FONT_COLOR + FontColor FONT_COLOR + FontStyle Bold + FontSize 30 +} + +skinparam package { + FontColor FONT_COLOR + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR +} +skinparam node { + FontColor FONT_COLOR + BackgroundColor BG_PACKAGE_COLOR + BorderColor BORDER_COLOR +} +skinparam component { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR + Style uml2 +} + +skinparam database { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} + +skinparam cloud { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} + +skinparam collections { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} +skinparam Control { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} +skinparam Boundary { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} +skinparam Entity { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} +skinparam interface { + BackgroundColor BG_MAIN_COLOR + BorderColor BORDER_COLOR + FontColor FONT_COLOR +} +skinparam SequenceParticipantBorderThickness 3 +skinparam sequence { + ParticipantBackgroundColor BG_MAIN_COLOR + ParticipantBorderColor BORDER_COLOR + ParticipantFontStyle normal + ParticipantFontColor FONT_COLOR + LifeLineBorderColor BORDER_COLOR + LifeLineBackgroundColor BG_MAIN_COLOR + ArrowColor FONT_COLOR + ArrowBorderColor BORDER_COLOR + ArrowFontColor FONT_COLOR + ArrowThickness 3 + ActorBackgroundColor BG_MAIN_COLOR + ActorBorderColor BORDER_COLOR + ActorFontColor FONT_COLOR +} \ No newline at end of file diff --git a/docs/docs/diagrams/includes/themes/light.puml b/docs/docs/diagrams/includes/themes/light.puml new file mode 100644 index 00000000..7f71afcf --- /dev/null +++ b/docs/docs/diagrams/includes/themes/light.puml @@ -0,0 +1,11 @@ +!define BG_MAIN_COLOR AliceBlue +!define BG_SECONDARY_COLOR #B4BCBE +!define BG_PACKAGE_COLOR #eeb291 +!define BORDER_COLOR #444444 +!define FONT_COLOR #444444 +!define ARROW_COLOR DarkGrey + + +' include the general skinparams for both, light and dark +' to overwrite with the given settings +!include general.puml \ No newline at end of file diff --git a/docs/diagrams/sequence.puml b/docs/docs/diagrams/sequence.puml similarity index 73% rename from docs/diagrams/sequence.puml rename to docs/docs/diagrams/sequence.puml index 0107ee5f..40cd5228 100644 --- a/docs/diagrams/sequence.puml +++ b/docs/docs/diagrams/sequence.puml @@ -1,19 +1,7 @@ @startuml -skinparam participant { - BackgroundColor AliceBlue - ArrowColor DarkGrey - BorderColor DarkGrey -} -skinparam roundcorner 20 +!include diagrams/includes/themes/light.puml -skinparam sequence { - ArrowColor DarkGrey - ActorBorderColor DarkGrey - LifeLineBorderColor DarkGrey - LifeLineBackgroundColor #A9DCDF - -} skinparam sequenceMessageAlign center autonumber "(0)" diff --git a/docs/diagrams/srv_sequence.puml b/docs/docs/diagrams/srv_sequence.puml similarity index 60% rename from docs/diagrams/srv_sequence.puml rename to docs/docs/diagrams/srv_sequence.puml index 492e456b..bd612a6f 100644 --- a/docs/diagrams/srv_sequence.puml +++ b/docs/docs/diagrams/srv_sequence.puml @@ -1,19 +1,6 @@ @startuml -skinparam participant { - BackgroundColor AliceBlue - ArrowColor DarkGrey - BorderColor DarkGrey -} +!include diagrams/includes/themes/light.puml -skinparam roundcorner 20 - -skinparam sequence { - ArrowColor DarkGrey - ActorBorderColor DarkGrey - LifeLineBorderColor DarkGrey - LifeLineBackgroundColor #A9DCDF - -} skinparam sequenceMessageAlign center diff --git a/docs/diagrams/stork.puml b/docs/docs/diagrams/stork.puml similarity index 54% rename from docs/diagrams/stork.puml rename to docs/docs/diagrams/stork.puml index 219de5e3..2d70c8e9 100644 --- a/docs/diagrams/stork.puml +++ b/docs/docs/diagrams/stork.puml @@ -1,27 +1,20 @@ @startuml -skinparam class { - BackgroundColor AliceBlue - ArrowColor DarkGrey - BorderColor DarkGrey -} +!include diagrams/includes/themes/light.puml hide members -class Stork <> #line.bold;line:CornflowerBlue +class Stork <> interface ServiceDiscovery -interface ServiceInstance #line.bold;line:CornflowerBlue +interface ServiceInstance interface LoadBalancer -interface ConfigProvider <> -class Service <> #line.bold;line:CornflowerBlue +class Service <> -Stork --[dotted] ConfigProvider Stork -- "*" Service Service -- ServiceDiscovery -Service -- "0..1" LoadBalancer +Service -- LoadBalancer Service --[dotted] ServiceInstance: selectServiceInstance class Kubernetes implements ServiceDiscovery class Consul implements ServiceDiscovery -class Static implements ServiceDiscovery class "Custom Service Discovery" implements ServiceDiscovery class RoundRobin<> implements LoadBalancer diff --git a/docs/extra.css b/docs/docs/extra.css similarity index 100% rename from docs/extra.css rename to docs/docs/extra.css diff --git a/docs/docs/images/problem-dark.png b/docs/docs/images/problem-dark.png new file mode 100644 index 00000000..4c601386 Binary files /dev/null and b/docs/docs/images/problem-dark.png differ diff --git a/docs/docs/images/problem-light.png b/docs/docs/images/problem-light.png new file mode 100644 index 00000000..cc0cff15 Binary files /dev/null and b/docs/docs/images/problem-light.png differ diff --git a/docs/images/redhat_reversed.svg b/docs/docs/images/redhat_reversed.svg similarity index 100% rename from docs/images/redhat_reversed.svg rename to docs/docs/images/redhat_reversed.svg diff --git a/docs/docs/images/solution-dark.png b/docs/docs/images/solution-dark.png new file mode 100644 index 00000000..800d0f97 Binary files /dev/null and b/docs/docs/images/solution-dark.png differ diff --git a/docs/docs/images/solution-light.png b/docs/docs/images/solution-light.png new file mode 100644 index 00000000..044bd378 Binary files /dev/null and b/docs/docs/images/solution-light.png differ diff --git a/docs/images/stork-white.png b/docs/docs/images/stork-white.png similarity index 100% rename from docs/images/stork-white.png rename to docs/docs/images/stork-white.png diff --git a/docs/index.md b/docs/docs/index.md similarity index 91% rename from docs/index.md rename to docs/docs/index.md index 0b5b57be..77161f3f 100644 --- a/docs/index.md +++ b/docs/docs/index.md @@ -24,14 +24,16 @@ Nevertheless, a modern distributed system or microservice-based application typi IPs get randomly assigned, and instances can be created or destroyed at any time. With such dynamics, hard-coded locations are a dead-end. -![the problem](images/problem.png) +![the problem](images/problem-light.png#only-light) +![the problem](images/problem-dark.png#only-dark) ## The solution Stork handles the service lookup and selection. It proposes an extensible set of service discovery mechanisms and load-balancing strategies. -![the solution](images/solution.png) +![the solution](images/solution-light.png#only-light) +![the solution](images/solution-dark.png#only-dark) ## What if the infrastructure provides such a feature? diff --git a/docs/load-balancer/custom-load-balancer.md b/docs/docs/load-balancer/custom-load-balancer.md similarity index 96% rename from docs/load-balancer/custom-load-balancer.md rename to docs/docs/load-balancer/custom-load-balancer.md index 38699409..8aa6f587 100644 --- a/docs/load-balancer/custom-load-balancer.md +++ b/docs/docs/load-balancer/custom-load-balancer.md @@ -49,7 +49,7 @@ Any configuration properties that the provider expects should be defined with `@ A load balancer provider class should look as follows: ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeLoadBalancerProvider.java" +--8<-- "snippets/examples/AcmeLoadBalancerProvider.java" ``` Note, that the `LoadBalancerProvider` interface takes a configuration class as a parameter. @@ -61,7 +61,7 @@ The next step is to implement the `LoadBalancer` interface. The essence of load balancers' work happens in the `selectServiceInstance` method. The method returns a single `ServiceInstance` from a collection. ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeLoadBalancer.java" +--8<-- "snippets/examples/AcmeLoadBalancer.java" ``` This implementation is simplistic and just picks a random instance from the received list. @@ -98,7 +98,7 @@ When building your load balancer project, the configuration generator creates a This class can be used to configure your load balancer using the Stork programmatic API. ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeSelectorApiUsage.java" +--8<-- "snippets/examples/AcmeSelectorApiUsage.java" ``` Remember that attributes, like `my-attribute`, are declared using the `@LoadBalancerAttribute` annotation on the `LoadBalancerProvider` implementation. \ No newline at end of file diff --git a/docs/load-balancer/least-requests.md b/docs/docs/load-balancer/least-requests.md similarity index 100% rename from docs/load-balancer/least-requests.md rename to docs/docs/load-balancer/least-requests.md diff --git a/docs/load-balancer/power-of-two-choices.md b/docs/docs/load-balancer/power-of-two-choices.md similarity index 100% rename from docs/load-balancer/power-of-two-choices.md rename to docs/docs/load-balancer/power-of-two-choices.md diff --git a/docs/load-balancer/random.md b/docs/docs/load-balancer/random.md similarity index 100% rename from docs/load-balancer/random.md rename to docs/docs/load-balancer/random.md diff --git a/docs/load-balancer/response-time.md b/docs/docs/load-balancer/response-time.md similarity index 100% rename from docs/load-balancer/response-time.md rename to docs/docs/load-balancer/response-time.md diff --git a/docs/load-balancer/round-robin.md b/docs/docs/load-balancer/round-robin.md similarity index 100% rename from docs/load-balancer/round-robin.md rename to docs/docs/load-balancer/round-robin.md diff --git a/docs/load-balancer/sticky.md b/docs/docs/load-balancer/sticky.md similarity index 100% rename from docs/load-balancer/sticky.md rename to docs/docs/load-balancer/sticky.md diff --git a/docs/programmatic-api.md b/docs/docs/programmatic-api.md similarity index 87% rename from docs/programmatic-api.md rename to docs/docs/programmatic-api.md index 58e20487..e5d10f01 100644 --- a/docs/programmatic-api.md +++ b/docs/docs/programmatic-api.md @@ -13,7 +13,7 @@ Retrieve the ServiceInstance, which will provide the metadata to access the actu If your framework does not already provide a configured `Stork` instance, you need to do: ```java linenums="1" ---8<-- "docs/snippets/examples/InitializationExample.java" +--8<-- "snippets/examples/InitializationExample.java" ``` ## Adding service dynamically @@ -21,7 +21,7 @@ If your framework does not already provide a configured `Stork` instance, you ne To register a new `ServiceDefinition`, use the `defineIfAbsent` method: ```java linenums="1" ---8<-- "docs/snippets/examples/DefinitionExample.java" +--8<-- "snippets/examples/DefinitionExample.java" ``` The `ServiceDefinition` instances can be created from: @@ -36,7 +36,7 @@ Attributes from the service discovery and load balancer can be configured from t To list the service instances for a given service, or to select an instance according to the load balancer strategy, use the following code: ```java linenums="1" ---8<-- "docs/snippets/examples/LookupExample.java" +--8<-- "snippets/examples/LookupExample.java" ``` The lookup and selection methods are returning Uni as these processes are asynchronous. @@ -46,5 +46,5 @@ The lookup and selection methods are returning Uni as these processes are asynch The following snippet provides an _all in one_ example of the Stork programmatic API: ```java linenums="1" ---8<-- "docs/snippets/examples/StorkApiExample.java" +--8<-- "snippets/examples/StorkApiExample.java" ``` diff --git a/docs/quarkus.md b/docs/docs/quarkus.md similarity index 96% rename from docs/quarkus.md rename to docs/docs/quarkus.md index 130249b5..1d3ba867 100644 --- a/docs/quarkus.md +++ b/docs/docs/quarkus.md @@ -24,7 +24,7 @@ To use Stork to determine the actual address, set the scheme of the URI to `stor For example, the `HelloClient` below will use the Stork service called `hello-service` to determine the address of the destination, and `/hello` as the base path for queries: ```java linenums="1" ---8<-- "docs/snippets/examples/HelloClient.java" +--8<-- "snippets/examples/HelloClient.java" ``` ## The service @@ -62,4 +62,4 @@ quarkus.stork.hello-service.service-discovery.consul-port=8500 ``` !!! note -When no load-balancing is configured, Stork uses a round-robin. + When no load-balancing is configured, Stork uses a round-robin. diff --git a/docs/service-discovery/composite.md b/docs/docs/service-discovery/composite.md similarity index 100% rename from docs/service-discovery/composite.md rename to docs/docs/service-discovery/composite.md diff --git a/docs/service-discovery/consul.md b/docs/docs/service-discovery/consul.md similarity index 100% rename from docs/service-discovery/consul.md rename to docs/docs/service-discovery/consul.md diff --git a/docs/service-discovery/custom-service-discovery.md b/docs/docs/service-discovery/custom-service-discovery.md similarity index 96% rename from docs/service-discovery/custom-service-discovery.md rename to docs/docs/service-discovery/custom-service-discovery.md index 89806999..37f4a2fd 100644 --- a/docs/service-discovery/custom-service-discovery.md +++ b/docs/docs/service-discovery/custom-service-discovery.md @@ -49,7 +49,7 @@ Any configuration properties that the provider expects should be defined with `@ A service discovery provider class should look as follows: ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeServiceDiscoveryProvider.java" +--8<-- "snippets/examples/AcmeServiceDiscoveryProvider.java" ``` Note, that the `ServiceDiscoveryProvider` interface takes a configuration class as a parameter. This configuration class @@ -59,7 +59,7 @@ Its name is created by appending `Configuration` to the service discovery type, The next step is to implement the `ServiceDiscovery` interface: ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeServiceDiscovery.java" +--8<-- "snippets/examples/AcmeServiceDiscovery.java" ``` This implementation is simplistic. @@ -98,7 +98,7 @@ This class can be used to configure your service discovery using the Stork progr ```java ```java linenums="1" ---8<-- "docs/snippets/examples/AcmeDiscoveryApiUsage.java" +--8<-- "snippets/examples/AcmeDiscoveryApiUsage.java" ``` Remember that attributes, like `host`, are declared using the `@ServiceDiscoveryAttribute` annotation on the `ServiceDiscoveryProvider` implementation. diff --git a/docs/service-discovery/dns.md b/docs/docs/service-discovery/dns.md similarity index 93% rename from docs/service-discovery/dns.md rename to docs/docs/service-discovery/dns.md index dbbc0a7e..37c75bfd 100644 --- a/docs/service-discovery/dns.md +++ b/docs/docs/service-discovery/dns.md @@ -16,7 +16,9 @@ They contain a _weight_, a _target_ and a _port_ for a service instance. The _target_ returned in an _SRV_ record needs to be resolved further by an _A_ or an _AAAA_ record. In short, it works as follows: -![SRV resolution](../target/srv_sequence.png) + +![DNS service discovery](../target/srv_sequence.svg#only-light) +![DNS service discovery](../target/srv_sequence_dark.svg#only-dark) ## Dependency diff --git a/docs/service-discovery/eureka.md b/docs/docs/service-discovery/eureka.md similarity index 100% rename from docs/service-discovery/eureka.md rename to docs/docs/service-discovery/eureka.md diff --git a/docs/service-discovery/kubernetes.md b/docs/docs/service-discovery/kubernetes.md similarity index 100% rename from docs/service-discovery/kubernetes.md rename to docs/docs/service-discovery/kubernetes.md diff --git a/docs/service-discovery/static-list.md b/docs/docs/service-discovery/static-list.md similarity index 100% rename from docs/service-discovery/static-list.md rename to docs/docs/service-discovery/static-list.md diff --git a/docs/images/problem.png b/docs/images/problem.png deleted file mode 100644 index c33ec3e1..00000000 Binary files a/docs/images/problem.png and /dev/null differ diff --git a/docs/images/solution.png b/docs/images/solution.png deleted file mode 100644 index a3c83206..00000000 Binary files a/docs/images/solution.png and /dev/null differ diff --git a/docs/mkdocs-customizations/macros/docissimo.py b/docs/mkdocs-customizations/macros/docissimo.py new file mode 100644 index 00000000..2b1d6207 --- /dev/null +++ b/docs/mkdocs-customizations/macros/docissimo.py @@ -0,0 +1,156 @@ +""" +Ease documentation writing with mkdocs + +- load the content of the 'variables.yaml' file +- provide the {{insert(file, tag)} macro + +## Loading attributes + +This feature loads a yaml file (default is `docs/attributes.yaml`), and import the content into the environment. +For example, if the imported file contains: + +``` +attributes: + versions: + camel: 3.13.0 + spec: 2.0.1 + mutiny: 1.1.2 + project-version: '3.14.0-SNAPSHOT' + smallrye-config-version: '2.7.0' +``` + +You can access values using `{{ attributes.versions.camel}}` or `{{ attributes['project-version'] }}`. + +The loaded file is `docs/variables.yaml` by default. The location can be configured in the `mkdocs.yml` file with: + +``` +extra: + attributes_path: docs/my-attributes.yaml +``` + +## Partial file include + +This feature allows including part of a file. +For example, include the code from the `Foo.java` located between `` and `` + +```java linenums="1" +{{ insert('src/test/Foo.java', 'example') }} +``` + +The `Foo.java` file contain something like: + +``` +package test; + +public class Foo { + + // this is my snippet + public static void main(String[]args){ + System.out.println("yoohoo"); + } + // + +} +``` + +The file path is relative to the `docs` directory. +You can change the location using the `snippet_dir` attributes in the `mkdocs.yaml` file: + +``` +extra: + snippet_dir: docs/snippets/src +``` + +Then, insert your snippet using: + +```java linenums="1" +{{ insert('test/Foo.java', 'example') }} +``` +""" + +import math +import yaml +import textwrap +import os.path + + +def loadAttributes(env): + path = env.conf['docs_dir'] + "/attributes.yaml" + if 'attributes_path' in env.variables: + path = env.variables['attributes_path'] + + if os.path.exists(path): + file = open(path) + var = yaml.load(file, Loader=yaml.FullLoader) + file.close() + if var is not None: + env.variables['attributes'] = var['attributes'] + else: + print("Unable to import attributes - " + path + " does not exists") + +def define_env(env): + + loadAttributes(env) + + @env.macro + def insert(file, tag = None): + root = env.conf['docs_dir'] + if 'snippet_dir' in env.variables: + root = env.variables['snippet_dir'] + + f = open(root + "/" + file) + + if tag is None: + text = f.read() + f.close() + return textwrap.dedent(text) + + inRecordingMode = False + c = "" + for line in f: + if not inRecordingMode: + if "<" + tag + ">" in line: + inRecordingMode = True + elif "" in line: + inRecordingMode = False + else: + c += line + + f.close() + if not c: + raise Exception(f"Unable to find tag '{tag}' in '{file}'") + + c = textwrap.dedent(c) + return c + + @env.macro + def image(path, title): + return f"""
+ {title} +
{title}
+
""" + + @env.macro + def javadoc(clazz, full = False, artifact = None): + version = env.variables.attributes['project-version'] + if (artifact is None) : + artifact = env.variables['javadoc_artifact'] + + if not artifact: + raise Exception("Missing configuration: 'extra.javadoc_artifact'") + + if not version: + version = 'latest' + + path = clazz.replace(".", "/") + ".html" + if full : + name = clazz + else : + name = clazz.rsplit('.', 1)[1] + return f"""{name}""" + + @env.filter + def reverse(x): + "Reverse a string (and uppercase)" + return x.upper()[::-1] + diff --git a/docs/mkdocs-customizations/overrides/main.html b/docs/mkdocs-customizations/overrides/main.html new file mode 100644 index 00000000..097b4b9d --- /dev/null +++ b/docs/mkdocs-customizations/overrides/main.html @@ -0,0 +1,8 @@ +{% extends "base.html" %} + +{% block outdated %} +You are not viewing the latest version. + + Click here to go to latest. + +{% endblock %} diff --git a/docs/mkdocs-customizations/overrides/partials/copyright.html b/docs/mkdocs-customizations/overrides/partials/copyright.html new file mode 100644 index 00000000..c657d1ff --- /dev/null +++ b/docs/mkdocs-customizations/overrides/partials/copyright.html @@ -0,0 +1,39 @@ + + + +
+
+ Sponsored by Red Hat
+ CC by 3.0 | + Privacy Policy +
+ {% if not config.extra.generator == false %} + Made with + + Material for MkDocs + + {% endif %} +
\ No newline at end of file diff --git a/mkdocs.yml b/docs/mkdocs.yml similarity index 61% rename from mkdocs.yml rename to docs/mkdocs.yml index 2dc0519d..7be9cf38 100644 --- a/mkdocs.yml +++ b/docs/mkdocs.yml @@ -1,6 +1,7 @@ site_name: Smallrye Stork repo_url: https://github.com/smallrye/smallrye-stork edit_uri: edit/main/docs/ +docs_dir: docs nav: - Overview: 'index.md' @@ -34,52 +35,94 @@ copyright: >- theme: name: material palette: - primary: black - accent: grey + - media: "(prefers-color-scheme: light)" + scheme: default + primary: black + accent: grey + toggle: + icon: material/lightbulb-night + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: black + accent: orange + toggle: + icon: material/lightbulb-on + name: Switch to light mode font: - text: Red Hat Text + text: Roboto code: Ubuntu Mono + icon: + repo: fontawesome/brands/github logo: images/stork-white.png favicon: images/stork-white.png features: - navigation.sections - content.tabs.link - content.code.annotate + - navigation.instant + - navigation.indexes + - navigation.tracking + - navigation.tabs.sticky extra_css: - extra.css extra_javascript: - - javascripts/mathjax.js - https://polyfill.io/v3/polyfill.min.js?features=es6 - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js markdown_extensions: - - pymdownx.highlight - - pymdownx.superfences + - toc: + permalink: '#' + - admonition + - smarty + - attr_list + - md_in_html + - meta + - tables + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.superfences: + custom_fences: + - name: mermaid + class: mermaid + format: !!python/name:pymdownx.superfences.fence_code_format - pymdownx.snippets + - pymdownx.inlinehilite + - pymdownx.details + - pymdownx.smartsymbols + - pymdownx.betterem - pymdownx.tabbed: alternate_style: true - - admonition - pymdownx.arithmatex: generic: true + - pymdownx.emoji: + emoji_index: !!python/name:materialx.emoji.twemoji + emoji_generator: !!python/name:materialx.emoji.to_svg plugins: - search - build_plantuml: render: "server" - server: "http://www.plantuml.com/plantuml" - output_format: "png" + server: "https://www.plantuml.com/plantuml" + output_format: "svg" diagram_root: "docs" output_folder: "target" input_folder: "diagrams" input_extensions: "puml" + theme_enabled: true + theme_folder: "include/themes" + theme_light: "light.puml" + theme_dark: "dark.puml" - macros - extra: + snippet_dir: snippets + javadoc_artifact: io.smallrye.reactive/smallrye-stork manifest: manifest.webmanifest version: - current: !ENV [STORK_VERSION, "SNAPSHOT"] + current: !ENV [ STORK_VERSION, "SNAPSHOT" ] provider: mike +