Add CMake support and enhance the getting started docs

- Add a root CMakeLists.txt defining an INTERFACE target. - Add CMake, qpm, Git and download installation instructions. - Add CMake and qmake integration instructions. - Remove smooth scroll when navigating the docs. - Add links validation to `npm run docs:link`. - Reorganize the sidebar API Reference section.
2024-11-21 18:24:29 +08:00 · 2020-01-09 20:41:09 +01:00 · 2020-01-09 20:41:09 +01:00 · 7f9013a878
commit 7f9013a878
parent cc29ef3512
12 changed files with 260 additions and 75 deletions
--- a/.gitignore
+++ b/.gitignore
@ -1,5 +1,6 @@
-dist
-node_modules
+/build
+/dist
+/node_modules
 *.gcno
 *.gcda
 *.info
--- a/.remarkrc.yml
+++ b/.remarkrc.yml
@ -1,5 +1,6 @@
 plugins:
  - frontmatter
+  - validate-links
  - preset-lint-recommended
  - preset-lint-markdown-style-guide
  - [lint-maximum-line-length, 100]
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@ -0,0 +1,15 @@
+cmake_minimum_required(VERSION 3.8)
+
+project(qtpromise VERSION 0.5.0 LANGUAGES CXX)
+
+find_package(Qt5 5.6.0 REQUIRED COMPONENTS Core)
+
+set(CMAKE_CXX_STANDARD 11)
+set(CMAKE_CXX_STANDARD_REQUIRED on)
+
+add_library(qtpromise INTERFACE)
+add_library(qtpromise::qtpromise ALIAS qtpromise)
+
+target_link_libraries(qtpromise INTERFACE Qt5::Core)
+
+target_include_directories(qtpromise INTERFACE "${CMAKE_CURRENT_LIST_DIR}/include")
--- a/docs/.vuepress/config.js
+++ b/docs/.vuepress/config.js
@ -9,8 +9,9 @@ module.exports = {
    themeConfig: {
        repo: 'simonbrunel/qtpromise',
        lastUpdated: 'Last Updated',
-        smoothScroll: true,
+        smoothScroll: false,
        editLinks: true,
+        sidebarDepth: 2,
        docsDir: 'docs',
        algolia: {
            apiKey: '0e6e9cccb8c2c360a5543e28c4e31cb8',
@ -26,7 +27,11 @@ module.exports = {
            '/qtpromise/qtconcurrent',
            '/qtpromise/qtsignals',
            '/qtpromise/thread-safety',
-            '/qtpromise/api-reference',
+            {
+                title: 'API Reference',
+                path: '/qtpromise/api-reference',
+                children: [
+                    //['/qtpromise/api-reference', 'Overview'],
                    {
                        title: 'QPromise',
                        children: [
@ -46,8 +51,8 @@ module.exports = {
                            '/qtpromise/qpromise/then',
                            '/qtpromise/qpromise/timeout',
                            '/qtpromise/qpromise/wait',
-                    '/qtpromise/qpromise/reject.md',
-                    '/qtpromise/qpromise/resolve.md'
+                            '/qtpromise/qpromise/reject',
+                            '/qtpromise/qpromise/resolve'
                        ]
                    },
                    {
@ -74,4 +79,6 @@ module.exports = {
                    }
                ]
            }
+        ]
+    }
 }
--- a/docs/.vuepress/styles/index.styl
+++ b/docs/.vuepress/styles/index.styl
@ -19,7 +19,7 @@ sup
    #main-title
        display none !important

-.content a code
+.page a code
    color $accentColor

 .navbar
--- a/docs/README.md
+++ b/docs/README.md
@ -1,7 +1,6 @@
 ---
 home: true
 heroImage: /hero.svg
-actionLink: /qtpromise/getting-started.md
 footer: MIT Licensed | Copyright © 2019 Simon Brunel
 ---

--- a/docs/qtpromise/getting-started.md
+++ b/docs/qtpromise/getting-started.md
@ -2,44 +2,152 @@

 ## Installation

-QtPromise is a [header-only](https://en.wikipedia.org/wiki/Header-only) library, simply download the
-[latest release](https://github.com/simonbrunel/qtpromise/releases/latest) (or [`git submodule`](https://git-scm.com/docs/git-submodule))
-and include `qtpromise.pri` from your project `.pro`.
+### Using CMake

-### qpm
+*Since: 0.6.0*

-Alternatively and **only** if your project relies on [qpm](https://www.qpm.io/), you can install
-QtPromise as follow:
+If your project uses [CMake](https://cmake.org/) as build system, QtPromise can be installed using
+the `FetchContent` module. Please refer to the [CMake (FetchContent)](#cmake-fetchcontent) section
+for details of using this method.

-```bash
+### Using qpm
+
+If your project is configured to use [qpm](https://www.qpm.io/), QtPromise can be installed using
+the following command:
+
+```sh
 qpm install com.github.simonbrunel.qtpromise
 ```

-## Usage
+See also: [com.github.simonbrunel.qtpromise](https://www.qpm.io/packages/com.github.simonbrunel.qtpromise/)

-The recommended way to use QtPromise is to include the single module header:
+### Using Git
+
+If your project uses [Git](https://git-scm.com/) as version control system, QtPromise can be
+installed either as a [`subtree`](#subtree) or a [`submodule`](#submodule). Read more about these
+commands in ["Git: submodules vs subtrees"](https://nering.dev/2016/git-submodules-vs-subtrees/)
+which provides a good comparison between these two workflows.
+
+The following examples install QtPromise version 0.5.0 under the `3rdparty/qtpromise` subdirectory.
+Note that the install directory is arbitrary and can be any empty directory under your repository.
+Once installed, refer to the [CMake](#cmake) or [qmake](#qmake) sections for details of integrating
+QtPromise into your project.
+
+#### subtree
+
+```sh
+cd <your/project/repository>
+git remote add qtpromise https://github.com/simonbrunel/qtpromise.git
+git subtree add -P 3rdparty/qtpromise qtpromise v0.5.0 --squash -m "Add QtPromise v0.5.0"
+```
+
+#### submodule
+
+```sh
+cd <your/project/repository>
+git submodule add https://github.com/simonbrunel/qtpromise.git 3rdparty/qtpromise
+cd 3rdparty/qtpromise
+git checkout v0.5.0
+cd ../..
+git add 3rdparty/qtpromise
+git commit -m "Add QtPromise v0.5.0"
+```
+
+### Download
+
+QtPromise can be downloaded from the [GitHub release page](https://github.com/simonbrunel/qtpromise/releases)
+as a `zip` or `tar.gz` archive. Under Linux, you can use the following commands:
+
+```sh
+cd <your/project/repository>
+wget -q -O qtpromise.tar.gz https://github.com/simonbrunel/qtpromise/archive/v0.5.0.tar.gz
+tar xzf qtpromise.tar.gz --strip 1 --one-top-level=3rdparty/qtpromise
+rm qtpromise.tar.gz
+```
+
+## Integration
+
+QtPromise is a [header-only](https://en.wikipedia.org/wiki/Header-only) library. Integrating it
+within your project consists only in configuring the include path(s) to the library headers. To
+simplify this step, [qmake](#qmake) and [CMake](#cmake) integrations are provided.
+
+### CMake
+
+*Since: 0.6.0*
+
+After installing QtPromise using [Git](#using-git) or the [download](#download) method, you can use
+the [`add_subdirectory`](https://cmake.org/cmake/help/latest/command/add_subdirectory.html) command
+to make its targets available to your CMake project:
+
+```cmake
+add_subdirectory(<path/to/qtpromise>)
+
+target_link_libraries(<target> qtpromise)
+```
+
+### CMake (FetchContent)
+
+*Since: 0.6.0*
+
+Alternatively, the [`FetchContent`](https://cmake.org/cmake/help/latest/module/FetchContent.html)
+module (**CMake 3.11+**) allows to install QtPromise from your CMake project at configure time:
+
+```cmake
+include(FetchContent)
+
+FetchContent_Declare(qtpromise
+  GIT_REPOSITORY https://github.com/simonbrunel/qtpromise.git
+  GIT_TAG origin/v0.6.0
+  GIT_SHALLOW true
+)
+
+# CMake v3.14+
+FetchContent_MakeAvailable(qtpromise)
+
+target_link_libraries(<target> qtpromise)
+```
+
+If your CMake version **is prior to v3.14**, you need to explicitly define the population steps:
+
+```cmake
+# CMake v3.11+ (alternative for FetchContent_MakeAvailable)
+FetchContent_GetProperties(qtpromise)
+if(NOT qtpromise_POPULATED)
+  FetchContent_Populate(qtpromise)
+  add_subdirectory(
+    ${qtpromise_SOURCE_DIR}
+    ${qtpromise_BINARY_DIR}
+  )
+endif()
+```
+
+### qmake
+
+After installing QtPromise using [Git](#using-git) or the [download](#download) method, you can
+[include](https://doc.qt.io/qt-5/qmake-test-function-reference.html#include-filename) `qtpromise.pri`
+file from the install directory:
+
+```cmake
+include(<path/to/qtpromise>/qtpromise.pri)
+```
+
+## Example
+
+To start using QtPromise in your code, you first need to include the single module header:

 ```cpp
 #include <QtPromise>
 ```

-## Example
-
-Let's first make the code more readable by using the library namespace:
+The following `download` function creates a [promise from callbacks](qpromise/constructor.md) which
+will be resolved when the network request is finished:

 ```cpp
-using namespace QtPromise;
-```
-
-This `download` function creates a [promise from callbacks](qpromise/constructor.md) which will be
-resolved when the network request is finished:
-
-```cpp
-QPromise<QByteArray> download(const QUrl& url)
+QtPromise::QPromise<QByteArray> download(const QUrl& url)
 {
-    return QPromise<QByteArray>([&](
-        const QPromiseResolve<QByteArray>& resolve,
-        const QPromiseReject<QByteArray>& reject) {
+    return QtPromise::QPromise<QByteArray>([&](
+        const QtPromise::QPromiseResolve<QByteArray>& resolve,
+        const QtPromise::QPromiseReject<QByteArray>& reject) {

        QNetworkReply* reply = manager->get(QNetworkRequest(url));
        QObject::connect(reply, &QNetworkReply::finished, [=]() {
@ -58,7 +166,7 @@ QPromise<QByteArray> download(const QUrl& url)
 The following method `uncompress` data in a separate thread and returns a [promise from QFuture](qtconcurrent.md):

 ```cpp
-QPromise<Entries> uncompress(const QByteArray& data)
+QtPromise::QPromise<Entries> uncompress(const QByteArray& data)
 {
    return QtPromise::resolve(QtConcurrent::run([](const QByteArray& data) {
        Entries entries;
--- a/docs/qtpromise/helpers/connect.md
+++ b/docs/qtpromise/helpers/connect.md
@ -17,7 +17,7 @@ Creates a `QPromise<T>` that will be fulfilled with the `resolver` signal's firs

 The second `(2)` and third `(3)` variants of this method will reject the `output` promise when the
 `rejecter` signal is emitted. The rejection reason is the value of the `rejecter` signal's first
-argument or [`QPromiseUndefinedException`](../exceptions/undefined) if `rejected` doesn't provide
+argument or [`QPromiseUndefinedException`](../exceptions/undefined.md) if `rejected` doesn't provide
 any argument.

 Additionally, the `output` promise will be automatically rejected with [`QPromiseContextException`](../exceptions/context.md)
--- a/docs/qtpromise/qtsignals.md
+++ b/docs/qtpromise/qtsignals.md
@ -59,7 +59,7 @@ output.then([](const QByteArray& data) {
 ```

 If the rejection signal doesn't provide any argument, the promise will be rejected with
-[`QPromiseUndefinedException`](../exceptions/undefined), for example:
+[`QPromiseUndefinedException`](exceptions/undefined.md), for example:

 ```cpp
 // [signal] Object::finished()
--- a/package-lock.json
+++ b/package-lock.json
@ -4771,6 +4771,23 @@
        "assert-plus": "^1.0.0"
      }
    },
+    "github-slugger": {
+      "version": "1.2.1",
+      "resolved": "https://registry.npmjs.org/github-slugger/-/github-slugger-1.2.1.tgz",
+      "integrity": "sha512-SsZUjg/P03KPzQBt7OxJPasGw6NRO5uOgiZ5RGXVud5iSIZ0eNZeNp5rTwCxtavrRUa/A77j8mePVc5lEvk0KQ==",
+      "dev": true,
+      "requires": {
+        "emoji-regex": ">=6.0.0 <=6.1.1"
+      },
+      "dependencies": {
+        "emoji-regex": {
+          "version": "6.1.1",
+          "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-6.1.1.tgz",
+          "integrity": "sha1-xs0OwbBkLio8Z6ETfvxeeW2k+I4=",
+          "dev": true
+        }
+      }
+    },
    "glob": {
      "version": "7.1.6",
      "resolved": "https://registry.npmjs.org/glob/-/glob-7.1.6.tgz",
@ -5023,6 +5040,12 @@
        }
      }
    },
+    "hosted-git-info": {
+      "version": "2.8.5",
+      "resolved": "https://registry.npmjs.org/hosted-git-info/-/hosted-git-info-2.8.5.tgz",
+      "integrity": "sha512-kssjab8CvdXfcXMXVcvsXum4Hwdq9XGtRD3TteMEvEbq0LXyiNQr6AprqKqfeaDXze7SxWvRxdpwE6ku7ikLkg==",
+      "dev": true
+    },
    "hpack.js": {
      "version": "2.1.6",
      "resolved": "https://registry.npmjs.org/hpack.js/-/hpack.js-2.1.6.tgz",
@ -5847,6 +5870,12 @@
        "invert-kv": "^2.0.0"
      }
    },
+    "levenshtein-edit-distance": {
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/levenshtein-edit-distance/-/levenshtein-edit-distance-1.0.0.tgz",
+      "integrity": "sha1-iVuvR4zOi1waDSfkXXwdl4pmHkk=",
+      "dev": true
+    },
    "linkify-it": {
      "version": "2.2.0",
      "resolved": "https://registry.npmjs.org/linkify-it/-/linkify-it-2.2.0.tgz",
@ -7847,6 +7876,15 @@
      "integrity": "sha1-mEcocL8igTL8vdhoEputEsPAKeM=",
      "dev": true
    },
+    "propose": {
+      "version": "0.0.5",
+      "resolved": "https://registry.npmjs.org/propose/-/propose-0.0.5.tgz",
+      "integrity": "sha1-SKBl2ex9TIZn9AULFcSi2F28pWs=",
+      "dev": true,
+      "requires": {
+        "levenshtein-edit-distance": "^1.0.0"
+      }
+    },
    "proxy-addr": {
      "version": "2.0.5",
      "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.5.tgz",
@ -8924,6 +8962,22 @@
        "xtend": "^4.0.1"
      }
    },
+    "remark-validate-links": {
+      "version": "9.1.0",
+      "resolved": "https://registry.npmjs.org/remark-validate-links/-/remark-validate-links-9.1.0.tgz",
+      "integrity": "sha512-vIVydrIhgVTkFmGHy24EVCVryc+IGJva4zK8fYdn+A/XkdO+4MxJlI9qk/kKMIucekomTP+Fg6Bf0Dw2gwCNdA==",
+      "dev": true,
+      "requires": {
+        "github-slugger": "^1.2.0",
+        "hosted-git-info": "^2.5.0",
+        "mdast-util-to-string": "^1.0.4",
+        "propose": "0.0.5",
+        "to-vfile": "^6.0.0",
+        "trough": "^1.0.0",
+        "unist-util-visit": "^1.0.0",
+        "xtend": "^4.0.0"
+      }
+    },
    "remove-trailing-separator": {
      "version": "1.1.0",
      "resolved": "https://registry.npmjs.org/remove-trailing-separator/-/remove-trailing-separator-1.1.0.tgz",
--- a/package.json
+++ b/package.json
@ -12,6 +12,7 @@
    "remark-frontmatter": "^1.3.2",
    "remark-preset-lint-markdown-style-guide": "^2.1.3",
    "remark-preset-lint-recommended": "^3.0.3",
+    "remark-validate-links": "^9.1.0",
    "vuepress": "^1.2.0"
  }
 }
--- a/package/features/qtpromise.prf
+++ b/package/features/qtpromise.prf
@ -1 +0,0 @@
-include(../../qtpromise.pri)