From bb2683f34b22387103141c836475c9f8a02f88fe Mon Sep 17 00:00:00 2001 From: Emil Dotchevski Date: Fri, 18 Dec 2020 21:32:47 -0800 Subject: [PATCH] Automatic documentation update on GitHub Actions --- .github/workflows/gh-pages.yml | 43 +++++++++++++++++++++++ doc/Jamfile | 4 +-- doc/qvm.adoc | 63 +++++++++++++++++++++------------- 3 files changed, 85 insertions(+), 25 deletions(-) create mode 100644 .github/workflows/gh-pages.yml diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml new file mode 100644 index 0000000..4569be0 --- /dev/null +++ b/.github/workflows/gh-pages.yml @@ -0,0 +1,43 @@ +name: documentation + +on: + push: + branches: + - master + +jobs: + publish: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + - name: Install packages + run: | + sudo gem install asciidoctor asciidoctor-pdf rouge + + - name: Setup Boost + run: | + REF=${GITHUB_BASE_REF:-$GITHUB_REF} + cd .. + git clone --depth 1 https://github.com/boostorg/boost.git boost-root + cd boost-root + cp -r $GITHUB_WORKSPACE/* libs/qvm + git submodule update --init tools/build + git submodule update --init libs/config + ./bootstrap.sh + + - name: Create user-config.jam + run: | + echo "using asciidoctor ;" > ~/user-config.jam + + - name: Build documentation + run: | + cd ../boost-root/libs/qvm/doc + ../../../b2 + + - name: Deploy to GitHub Pages + uses: JamesIves/github-pages-deploy-action@3.7.1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + BRANCH: gh-pages + FOLDER: ../boost-root/libs/qvm/doc/html diff --git a/doc/Jamfile b/doc/Jamfile index 2d755c0..5c8d103 100644 --- a/doc/Jamfile +++ b/doc/Jamfile @@ -9,9 +9,9 @@ project doc/qvm ; import asciidoctor ; html index.html : qvm.adoc : stylesheet=zajo-dark.css linkcss ; -install html_ : index.html skin.png zajo-dark.css zajo-light.css : html ; +install html_ : index.html skin.png zajo-dark.css zajo-light.css rouge-github.css : html ; -pdf qvm.pdf : qvm.adoc : book pdf-themesdir=doc pdf-theme=qvm ; +pdf qvm.pdf : qvm.adoc : book pdf-themesdir=. pdf-theme=qvm ; install pdf_ : qvm.pdf : html ; alias boostdoc ; diff --git a/doc/qvm.adoc b/doc/qvm.adoc index 7077c18..99ab34e 100644 --- a/doc/qvm.adoc +++ b/doc/qvm.adoc @@ -5,13 +5,8 @@ :stylesheet: zajo-dark.css :source-highlighter: rouge -ifdef::backend-pdf[] = QVM -endif::[] -ifndef::backend-pdf[] -= QVM pass:[
] -endif::[] -Quaternion / Vector / Matrix Library for {CPP}-11 | Emil Dotchevski +Quaternion / Vector / Matrix Library for {CPP}03 | Emil Dotchevski ifndef::backend-pdf[] :toc: left :toclevels: 3 @@ -27,9 +22,11 @@ QVM is a generic library for working with Quaternions, Vectors and Matrices of s ==== * Emphasis on 2, 3 and 4-dimensional operations needed in graphics, video games and simulation applications. -* Free function templates operate on any compatible user-defined quaternion, vector or matrix type. -* Quaternion, vector and matrix types from different libraries or subsystems can be safely mixed in the same expression. -* Type-safe mapping between compatible lvalue types with no temporary objects; e.g. transpose remaps the elements, rather than transforming the matrix. +* Free function templates operate on any compatible user-defined Quaternion, Vector or Matrix type. +* Enables Quaternion, Vector and Matrix types from different libraries to be safely mixed in the same expression. +* Type-safe mapping between compatible lvalue types with no temporary objects; f.ex. transpose remaps the access to the elements, rather than transforming the matrix. +* Requires only {CPP}03. +* Zero dependencies. ==== ifndef::backend-pdf[] @@ -138,7 +135,7 @@ User-defined quaternion types are similarly introduced to QVM by specializing th === C Arrays -In <>, <> and <> QVM defines appropriate <>, <> and <> specializations that allow QVM functions to operate directly on plain old C arrays: +In `boost/qvm/quat_traits_array.hpp`, `vec_traits_array.hpp` and `mat_traits_array.hpp`, QVM defines appropriate <>, <> and <> specializations that allow QVM functions to operate directly on plain old C arrays: [source,c++] ---- @@ -285,7 +282,7 @@ The answer is that by default, QVM returns some kind of compatible matrix type, [source,c++] ---- -auto & m = m1 * m2; +auto & m = m1 * m2; // auto requires C++11 ---- However, the type deduced by default converts implicitly to any compatible matrix type, so the following is also valid, at the cost of a temporary: @@ -502,7 +499,7 @@ namespace boost { namespace qvm { template struct deduce_scalar { - typedef typename impl::type type; + typedef typename /*exact definition unspecified*/ type; }; } } @@ -512,12 +509,23 @@ Requires: :: `A` and `B` satisfy the <> Returns: :: -If `A` and `B` are the same type, `impl::type` returns that type. Otherwise, `impl::type` is well defined for the following types only: `signed`/`unsigned char`, `signed`/`unsigned short`, `signed`/`unsigned int`, `signed`/`unsigned long`, `float` and `double`. The deduction logic is as follows: +If `A` and `B` are the same type, `scalar_traits::type` is defined as that type. Otherwise for the following types: + +* `signed`/`unsigned char`, +* `signed`/`unsigned short`, +* `signed`/`unsigned int`, +* `signed`/`unsigned long`, +* `float`, +* `double`, + +the deduction logic is as follows: - if either of `A` and `B` is `double`, the result is `double`; - else, if one of `A` or `B` is an integer type and the other is `float`, the result is `float`; - else, if one of `A` or `B` is a signed integer and the other type is unsigned integer, the signed type is changed to unsigned, and then the lesser of the two integers is promoted to the other. +For any other types `scalar_traits::type` is defined as `void`. It can be specialized for user-defined scalar types. + NOTE: This template is used by generic binary operations that return a scalar, to deduce the return type based on the (possibly different) scalars of their arguments. ''' @@ -713,7 +721,8 @@ The `quat_traits_defaults` template is designed to be used as a public base for ---- namespace boost { namespace qvm { - template ::scalar_type> + template ::scalar_type> struct deduce_quat { typedef Q type; }; @@ -723,12 +732,13 @@ namespace boost { namespace qvm { Requires: :: -- `<>::value` is `true`; +- `<>::value` is `true`; +- `<>::value` is `true`; - `<>::type>::value` must be `true`; -- `<>::type>::scalar_type` must be the same type as `S`. +- `<>::type>::scalar_type` must be the same type as `S`; - `deduce_quat::type` must be copyable. -This template is used by QVM whenever it needs to deduce a copyable quaternion type from a single user-supplied function parameter of quaternion type. Note that `Q` itself may be non-copyable. +This template is used by QVM whenever it needs to deduce a copyable quaternion type from the quaternion type `Q`, with a scalar type `S`. Note that `Q` itself may be non-copyable. The main template definition returns an unspecified quaternion type, except if `S` is the same type as `<>::scalar_type`, in which case it returns `Q`, which is only suitable if `Q` is copyable. QVM also defines (partial) specializations for the non-copyable quaternion types it produces. Users can define other (partial) specializations for their own types. @@ -744,7 +754,10 @@ A typical use of the `deduce_quat` template is for specifying the preferred quat ---- namespace boost { namespace qvm { - template ::scalar_type> + template ::type, + typename scalar::type>::type> struct deduce_quat2 { typedef /*unspecified*/ type; }; @@ -756,11 +769,12 @@ Requires: :: - Both `<>::type` and `scalar::type` are well defined; - `<>::value` || `is_quat::value` is `true`; +- `<>::value` is `true`; - `is_quat::type>::value` must be `true`; -- `<>::type>::scalar_type` must be the same type as `S`. +- `<>::type>::scalar_type` must be the same type as `S`; - `deduce_quat2::type` must be copyable. -This template is used by QVM whenever it needs to deduce a quaternion type from the types of two user-supplied function parameters. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may not be a quaternion type.) +This template is used by QVM whenever it needs to deduce a quaternion type from the types of two user-supplied function parameters, with scalar type `S`. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may not be a quaternion type.) The main template definition returns an unspecified quaternion type with <> `S`, except if `A` and `B` are the same quaternion type `Q`, in which case `Q` is returned, which is only suitable for copyable types. QVM also defines (partial) specializations for the non-copyable quaternion types it produces. Users can define other (partial) specializations for their own types. @@ -988,9 +1002,10 @@ namespace boost { namespace qvm { Requires: :: - `<>::value` is `true`; +- `<>::value` is `true`; - `is_vec::type>::value` must be `true`; - `deduce_vec::type` must be copyable; -- `vec_traits::type>::dim==D`. +- `vec_traits::type>::dim==D`; - `vec_traits::type>::scalar_type` is the same type as `S`. This template is used by QVM whenever it needs to deduce a copyable vector type of certain dimension from a single user-supplied function parameter of vector type. The returned type must have accessible copy constructor. Note that `V` may be non-copyable. @@ -1010,7 +1025,7 @@ A typical use of the `deduce_vec` template is for specifying the preferred vecto namespace boost { namespace qvm { template ::type, typename scalar::type>::type> struct deduce_vec2 { @@ -1024,12 +1039,13 @@ Requires: :: - Both `<>::type` and `scalar::type` are well defined; - `<>::value || is_vec::value` is `true`; +- `<>::value` is `true`; - `is_vec::type>::value` must be `true`; - `deduce_vec2::type` must be copyable; - `vec_traits::type>::dim==D`. - `vec_traits::type>::scalar_type` is the same type as `S`. -This template is used by QVM whenever it needs to deduce a vector type of certain dimension from the types of two user-supplied function parameters. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may not be a vector type.) +This template is used by QVM whenever it needs to deduce a vector type of certain dimension from the types of two user-supplied function parameters. The returned type must have accessible copy constructor (the `A` and `B` types themselves could be non-copyable, and either one of them may be a non-vector type.) The main template definition returns an unspecified vector type of the requested dimension with <> `S`, except if `A` and `B` are the same vector type `V`, in which case `V` is returned, which is only suitable for copyable types. QVM also defines (partial) specializations for the non-copyable vector types it produces. Users can define other (partial) specializations for their own types. @@ -1292,6 +1308,7 @@ Requires: :: - Both `<>::type` and `scalar::type` are well defined; - `<>::value || is_mat::value` is `true`; +- `<>::value` is `true`; - `is_mat::type>::value` must be `true`; - `deduce_mat2::type` must be copyable; - `<>::type>::rows==R`;