From e96469056b4e0386d7505035ca2e2c861d46b491 Mon Sep 17 00:00:00 2001 From: gggeek Date: Sat, 24 Dec 2022 10:17:08 +0000 Subject: [PATCH] doc updates; bring manual back into tarball --- .gitattributes | 4 ++- README.md | 52 +++++++++----------------------- doc/manual/phpxmlrpc_manual.adoc | 35 +++++++++++++++++++++ 3 files changed, 52 insertions(+), 39 deletions(-) diff --git a/.gitattributes b/.gitattributes index 29c3b37c..8faacf8b 100644 --- a/.gitattributes +++ b/.gitattributes @@ -3,7 +3,9 @@ .githooks/ export-ignore .github/ export-ignore demo/ export-ignore -doc/ export-ignore +doc/api_changes_v4.md export-ignore +doc/build/ export-ignore +doc/Changelog extras/ export-ignore tests/ export-ignore diff --git a/README.md b/README.md index e27fc973..ac6aef9c 100644 --- a/README.md +++ b/README.md @@ -4,56 +4,32 @@ A php library for building xml-rpc clients and servers. Requirements and Installation ----------------------------- + The recommended way to install this library is using Composer. Detailed installation instructions are in the [INSTALL.md](INSTALL.md) file, along with system requirements listing. Documentation ------------- -See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the -library main features and all project related information. - -The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc) - -Older release tarballs also contain HTML and PDF versions of the manual, as well as an automatically generated API -documentation. The documentation for the API is currently available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html) - -*NB: the user manual has not been updated yet with all the changes made in version 4. Please consider it unreliable!* - -*You are encouraged to look instead the code examples found in the demo/ directory* - -Upgrading ---------- -If you are upgrading from version 3 or earlier you have two options: -1. adapt your code to the new API (all changes needed are described in [doc/api_changes_v4.md](doc/api_changes_v4.md)) - -2. use instead the *compatibility layer* which is provided. Instructions and pitfalls described in [doc/api_changes_v4.md](doc/api_changes_v4.md##enabling-compatibility-with-legacy-code) - -In any case, read carefully the docs in [doc/api_changes_v4.md](doc/api_changes_v4.md) and report back any undocumented -issue using GitHub. - -Running tests -------------- - -The recommended way to run the library test suite is via the provided Docker containers. -A handy shell script is available that simplifies usage of Docker. +See the documentation page at [gggeek.github.io/phpxmlrpc](https://gggeek.github.io/phpxmlrpc) for a list of the +library main features and all project related information, including information about online resources such as debuggers +and demo servers. -The full sequence of operations is: +The user manual can be found in the doc/manual directory: [phpxmlrpc_manual.adoc](doc/manual/phpxmlrpc_manual.adoc). +It includes sections about upgrading from previous versions as well as running the library's testing suite. - ./tests/ci/vm.sh build - ./tests/ci/vm.sh start - ./tests/ci/vm.sh runtests - ./tests/ci/vm.sh stop +The manual is formatted as an asciidoc file - if viewing it locally, it is recommended to either use an IDE which can +natively render asciidoc, or view it as html via in-browser rendering by serving it via a webserver and accessing /doc/manual/index.html - # and, once you have finished all testing related work: - ./tests/ci/vm.sh cleanup +Automatically-generated documentation for the API is available online at [http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html](http://gggeek.github.io/phpxmlrpc/doc-4/api/index.html) -By default, tests are run using php 7.4 in a Container based on Ubuntu 20 Focal. -You can change the version of PHP and Ubuntu in use by setting the environment variables PHP_VERSION and UBUNTU_VERSION -before building the Container. +You are encouraged to look also at the code examples found in the demo/ directory. -To generate the code-coverage report, run `./tests/ci/vm.sh runcoverage` +Note: to reduce the size of the download, the demo files are not part of the default package installed with Composer. +You can either make sure they are available locally, by installing the library using Composer option `--prefer-install=source` +(when doing so, make sure that the demo folder is not directly accessible from the internet, ie. it is not within the +webserver root directory), or just check them out online at https://github.com/gggeek/phpxmlrpc/tree/master/demo. License ------- diff --git a/doc/manual/phpxmlrpc_manual.adoc b/doc/manual/phpxmlrpc_manual.adoc index 07428a8d..4cb4028b 100644 --- a/doc/manual/phpxmlrpc_manual.adoc +++ b/doc/manual/phpxmlrpc_manual.adoc @@ -1478,6 +1478,41 @@ components have to be downloaded separately and copied to the debugger directory and set appropriately the variable `+$editorpath+`. +== Upgrading + +If you are upgrading from version 3 or earlier you have two options: + +1. adapt your code to the new API (all changes needed are described in [doc/api_changes_v4.md](doc/api_changes_v4.md)) + +2. use instead the *compatibility layer* which is provided. Instructions and pitfalls described in [doc/api_changes_v4.md](doc/api_changes_v4.md##enabling-compatibility-with-legacy-code) + +In any case, read carefully the docs available online at https://github.com/gggeek/phpxmlrpc/blob/master/doc/api_changes_v4.md +and report back any undocumented issue using GitHub. + +== Running tests + +The recommended way to run the library's test suite is via the provided Docker containers. +A handy shell script is available that simplifies usage of Docker. + +The full sequence of operations is: + + ./tests/ci/vm.sh build + ./tests/ci/vm.sh start + ./tests/ci/vm.sh runtests + ./tests/ci/vm.sh stop + + # and, once you have finished all testing related work: + ./tests/ci/vm.sh cleanup + +By default, tests are run using php 7.4 in a Container based on Ubuntu 20 Focal. +You can change the version of PHP and Ubuntu in use by setting the environment variables PHP_VERSION and UBUNTU_VERSION +before building the Container. + +To generate the code-coverage report, run `./tests/ci/vm.sh runcoverage` + +Note: to reduce the size of the download, the test suite is not part of the default package installed with Composer. +In order to have it onboard, install the library using Composer option `--prefer-install=source`. + ++++++++++++++++++++++++++++++++++++++