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.

.gitignore

@@ -1,5 +1,6 @@
-dist
+/build
-node_modules
+/dist
+/node_modules
 *.gcno
 *.gcda
 *.info

.remarkrc.yml

@@ -1,5 +1,6 @@
 plugins:
   - frontmatter
+  - validate-links
   - preset-lint-recommended
   - preset-lint-markdown-style-guide
   - [lint-maximum-line-length, 100]

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")

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/reject',
-                    '/qtpromise/qpromise/resolve.md'
+                            '/qtpromise/qpromise/resolve'
                         ]
                     },
                     {
@@ -74,4 +79,6 @@ module.exports = {
                     }
                 ]
             }
+        ]
+    }
 }

docs/.vuepress/styles/index.styl

@@ -19,7 +19,7 @@ sup
     #main-title
         display none !important
 
-.content a code
+.page a code
     color $accentColor
 
 .navbar

docs/README.md

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

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
+### Using CMake
-[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`.
 
-### qpm
+*Since: 0.6.0*
 
-Alternatively and **only** if your project relies on [qpm](https://www.qpm.io/), you can install
+If your project uses [CMake](https://cmake.org/) as build system, QtPromise can be installed using
-QtPromise as follow:
+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
+The following `download` function creates a [promise from callbacks](qpromise/constructor.md) which
-
+will be resolved when the network request is finished:
-Let's first make the code more readable by using the library namespace:
 
 ```cpp
-using namespace QtPromise;
+QtPromise::QPromise<QByteArray> download(const QUrl& url)
-```
-
-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)
 {
-    return QPromise<QByteArray>([&](
+    return QtPromise::QPromise<QByteArray>([&](
-        const QPromiseResolve<QByteArray>& resolve,
+        const QtPromise::QPromiseResolve<QByteArray>& resolve,
-        const QPromiseReject<QByteArray>& reject) {
+        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;

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)

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()

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",

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"
   }
 }

package/features/qtpromise.prf

@@ -1 +0,0 @@
-include(../../qtpromise.pri)