From 2095e8788be7d5f6d5107895ea728ac6c6a914de Mon Sep 17 00:00:00 2001 From: "John L. Villalovos" Date: Wed, 9 Jul 2025 19:28:33 -0700 Subject: [PATCH 1/3] docs: remove convert script that is no longer needed --- docs/convert-docs.sh | 23 ----------------------- 1 file changed, 23 deletions(-) delete mode 100755 docs/convert-docs.sh diff --git a/docs/convert-docs.sh b/docs/convert-docs.sh deleted file mode 100755 index 6cb22261d..000000000 --- a/docs/convert-docs.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/bin/bash - -set -u -# set -e - -export PS4='+ ${BASH_SOURCE:-}:${FUNCNAME[0]:-}:L${LINENO:-}: ' -# set -x - -TOP_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && git rev-parse --show-toplevel)" - -echo "${TOP_DIR}" - -for filepath in "${TOP_DIR}"/doc/*.md -do - echo "${filepath}" - filename=$(basename -- "${filepath}") - extension="${filename##*.}" - filename="${filename%.*}" - if [[ "${filename}" == "README" ]]; then - filename="DEVELOPER-README" - fi - pandoc "${filepath}" -f markdown -t rst -o "${TOP_DIR}/docs/source/${filename}.rst" -done From 9f58247eda7994a51c3bfcb77c76483ce3b650d5 Mon Sep 17 00:00:00 2001 From: "John L. Villalovos" Date: Wed, 9 Jul 2025 19:19:58 -0700 Subject: [PATCH 2/3] docs: add link to API docs, use notes, update PHP version * Update the minimum PHP version to 8.2 in INSTALLATION.rst * Use the `.. notes::` feature in SAML-Configuration.rst * Add a link to the API documentation in INSTALLATION.rst --- docs/source/INSTALLATION.rst | 15 +++++++++------ docs/source/SAML-Configuration.rst | 28 +++++++++++++++++----------- 2 files changed, 26 insertions(+), 17 deletions(-) diff --git a/docs/source/INSTALLATION.rst b/docs/source/INSTALLATION.rst index bb907c459..e4e8a7cb5 100644 --- a/docs/source/INSTALLATION.rst +++ b/docs/source/INSTALLATION.rst @@ -331,7 +331,7 @@ client applications. Prerequisites ^^^^^^^^^^^^^ -- PHP 7.0 or greater +- PHP 8.2 or greater - To use ‘friendly’ URLs, mod_rewrite or URL rewriting must be enabled - Your web server must accept all verbs: GET, POST, PUT, DELETE @@ -348,11 +348,14 @@ Configuration API Documentation ^^^^^^^^^^^^^^^^^ -| Auto-generated documentation for API usage can be found by browsing - http://your_librebooking_url/Web/Services. -| This documentation describes each available service, indicates whether - or not the service is available to unauthenticated - users/administrators, and provides example requests/responses. +Auto-generated documentation for API usage can be found by browsing +http://your_librebooking_url/Web/Services. + +API documentation is also available at :doc:`API` + +This documentation describes each available service, indicates whether or not +the service is available to unauthenticated users/administrators, and provides +example requests/responses. Consuming the API ^^^^^^^^^^^^^^^^^ diff --git a/docs/source/SAML-Configuration.rst b/docs/source/SAML-Configuration.rst index 0a2e6d11d..cff68d0be 100644 --- a/docs/source/SAML-Configuration.rst +++ b/docs/source/SAML-Configuration.rst @@ -46,9 +46,12 @@ SimpleSAMLphp has a lot of configuration options. If you’re like me and far from an expert in SAML, it’s overwhelming. Luckily, since LibreBooking is a Service Provider it doesn’t need anything special. I’ll go through each of the settings that need to be updated -individually. Please note that at the time of writing this post, the -latest version of SimpleSAMLphp was 1.18.5. It’s possible that the names -of the options will change in future versions. +individually. + +.. note:: + At the time of writing this post, the latest version of SimpleSAMLphp was + 1.18.5. It’s possible that the names of the options will change in future + versions. Copy ``/home/username/simplesamlphp/config/config.php.dist`` to ``/home/username/simplesamlphp/config/config.php`` @@ -188,15 +191,18 @@ Some Restrictions A couple important notes with SAML enabled: -The first is that you will no longer be able to log into LibreBooking -with any other credentials. There is no “back door” – so every -authentication request will be routed through SAML. +.. warning:: + + You will no longer be able to log into LibreBooking with any other + credentials. There is no “back door” – so every authentication request will + be routed through SAML. + +.. warning:: -The other restriction is that you will not be able to use any -authenticated method from the API. SAML performs a series of browser -redirects in order to complete the authentication process. When using -the API you are not within the context of a browser, so authentication -will fail. + You will not be able to use any authenticated method from the API. SAML + performs a series of browser redirects in order to complete the + authentication process. When using the API you are not within the context + of a browser, so authentication will fail. Logging In ---------- From ea47481138510e3fab149615f049eaee24b9e8cf Mon Sep 17 00:00:00 2001 From: "John L. Villalovos" Date: Wed, 9 Jul 2025 19:30:39 -0700 Subject: [PATCH 3/3] docs(API): add notes about requiring trailing `/` for some calls Some of the calls require the trailing `/`. Make a note of that, as it is easy to make a mistake and not include it. --- docs/source/API.rst | 34 ++++++++++++++++++++++++++++++++-- 1 file changed, 32 insertions(+), 2 deletions(-) diff --git a/docs/source/API.rst b/docs/source/API.rst index b032fce9b..02f610979 100644 --- a/docs/source/API.rst +++ b/docs/source/API.rst @@ -49,7 +49,7 @@ Accessories POST Services ~~~~~~~~~~~~~ -na. +Not applicable. GET Services ~~~~~~~~~~~~ @@ -137,6 +137,11 @@ CreateAccount **Route:** ``/Web/Services/index.php/Accounts/`` +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** Unstructured response of type *AccountCreatedResponse* @@ -298,6 +303,11 @@ CreateCustomAttribute *This service is only available to application administrators* +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** .. code:: json @@ -619,6 +629,11 @@ Creates a new group *This service is only available to application administrators* +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** .. code:: json @@ -922,6 +937,11 @@ Creates a new reservation *This service is secure and requires authentication* +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** .. code:: json @@ -1466,6 +1486,11 @@ Creates a new resource *This service is only available to application administrators* +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** .. code:: json @@ -2047,7 +2072,7 @@ Schedules POST Services ~~~~~~~~~~~~~ -na. +Not applicable. .. _get-services-7: @@ -2307,6 +2332,11 @@ Creates a new user *This service is only available to application administrators* +.. note:: + + It is required for the route to end with the ``/`` character, or it will + fail. + **Response:** .. code:: json