Migrate documentation to VuePress

GitBook development seems a bit stuck right now so let's switch to VuePress which, IMO, is more user friendly. Update the documentation to include the version number in which features were added and use custom container to display notes and warnings.

README.md

@@ -1,6 +1,7 @@
 <a href="https://promisesaplus.com/" title="Promises/A+ 1.1"><img src="https://promisesaplus.com/assets/logo-small.png" alt="Promises/A+" align="right"/></a>
 
 # QtPromise
+
 [![qpm](https://img.shields.io/github/release/simonbrunel/qtpromise.svg?style=flat-square&label=qpm&colorB=4CAF50)](https://www.qpm.io/packages/com.github.simonbrunel.qtpromise/index.html) [![Travis](https://img.shields.io/travis/simonbrunel/qtpromise/master.svg?style=flat-square)](https://travis-ci.org/simonbrunel/qtpromise) [![coverage](https://img.shields.io/codecov/c/github/simonbrunel/qtpromise.svg?style=flat-square)](https://codecov.io/gh/simonbrunel/qtpromise)
 
 [Promises/A+](https://promisesaplus.com/) implementation for [Qt/C++](https://www.qt.io/).
@@ -9,10 +10,11 @@ Requires [Qt 5.6](https://www.qt.io/download/) (or later) with [C++11 support en
 
 ## Documentation
 
-* [Getting Started](https://qtpromise.netlify.com/qtpromise/getting-started)
+* [Getting Started](https://qtpromise.netlify.com/qtpromise/getting-started.html)
-* [Thread-Safety](https://qtpromise.netlify.com/qtpromise/thread-safety)
+* [QtConcurrent](https://qtpromise.netlify.com/qtpromise/qtconcurrent.html)
-* [QtConcurrent](https://qtpromise.netlify.com/qtpromise/qtconcurrent)
+* [Thread-Safety](https://qtpromise.netlify.com/qtpromise/thread-safety.html)
-* [API Reference](https://qtpromise.netlify.com/qtpromise/api-reference)
+* [API Reference](https://qtpromise.netlify.com/qtpromise/api-reference.html)
 
 ## License
+
 QtPromise is available under the [MIT license](LICENSE).

book.json

@@ -1,40 +0,0 @@
-{
-  "title": "QtPromise",
-  "description": "Promises/A+ implementation for Qt/C++",
-  "author": "Simon Brunel",
-  "gitbook": "3.2.3",
-  "root": "docs",
-  "plugins": [
-    "-lunr",
-    "-search",
-    "search-plus",
-    "anchorjs",
-    "edit-link",
-    "expand-active-chapter",
-    "ga",
-    "github"
-  ],
-  "pluginsConfig": {
-    "anchorjs": {
-      "icon": "#",
-      "placement": "left",
-      "visible": "always"
-    },
-    "edit-link": {
-      "base": "https://github.com/simonbrunel/qtpromise/edit/master/docs"
-    },
-    "ga": {
-      "token": "UA-113899811-1",
-      "configuration": "auto"
-    },
-    "github": {
-      "url": "https://github.com/simonbrunel/qtpromise"
-    },
-    "theme-default": {
-      "showLevel": false,
-      "styles": {
-        "website": "assets/style.css"
-      }
-    }
-  }
-}

docs/.vuepress/config.js

@@ -0,0 +1,54 @@
+module.exports = {
+    title: 'QtPromise',
+    description: 'Promises/A+ implementation for Qt/C++',
+    ga: 'UA-113899811-1',
+    head: [
+        ['link', { rel: 'icon', href: `/favicon.png` }],
+    ],
+    themeConfig: {
+        repo: 'simonbrunel/qtpromise',
+        lastUpdated: 'Last Updated',
+        editLinks: true,
+        docsDir: 'docs',
+        sidebar: [
+            'qtpromise/getting-started',
+            'qtpromise/qtconcurrent',
+            'qtpromise/thread-safety',
+            'qtpromise/api-reference',
+            {
+                title: 'QPromise',
+                children: [
+                    'qtpromise/qpromise/constructor',
+                    'qtpromise/qpromise/delay',
+                    'qtpromise/qpromise/each',
+                    'qtpromise/qpromise/fail',
+                    'qtpromise/qpromise/filter',
+                    'qtpromise/qpromise/finally',
+                    'qtpromise/qpromise/isfulfilled',
+                    'qtpromise/qpromise/ispending',
+                    'qtpromise/qpromise/isrejected',
+                    'qtpromise/qpromise/map',
+                    'qtpromise/qpromise/tap',
+                    'qtpromise/qpromise/tapfail',
+                    'qtpromise/qpromise/then',
+                    'qtpromise/qpromise/timeout',
+                    'qtpromise/qpromise/wait',
+                    'qtpromise/qpromise/all.md',
+                    'qtpromise/qpromise/reject.md',
+                    'qtpromise/qpromise/resolve.md'
+                ]
+            },
+            {
+                title: 'Helpers',
+                children: [
+                    'qtpromise/helpers/attempt',
+                    'qtpromise/helpers/each',
+                    'qtpromise/helpers/filter',
+                    'qtpromise/helpers/map',
+                    'qtpromise/helpers/qpromise',
+                    'qtpromise/helpers/qpromiseall'
+                ]
+            }
+        ]
+    }
+}

docs/.vuepress/override.styl

@@ -0,0 +1,2 @@
+$accentColor = #23b223
+$textColor = #404244

docs/.vuepress/style.styl

@@ -0,0 +1,4 @@
+@import 'override.styl'
+
+.content a code
+    color: $accentColor

docs/README.md

@@ -5,11 +5,5 @@
 
 Requires [Qt 5.6](https://www.qt.io/download/) (or later) with [C++11 support enabled](https://wiki.qt.io/How_to_use_C++11_in_your_Qt_Projects).
 
-## QtPromise for C++
-* [Getting Started](qtpromise/getting-started.md)
-* [Thread-Safety](qtpromise/thread-safety.md)
-* [QtConcurrent](qtpromise/qtconcurrent.md)
-* [API Reference](qtpromise/api-reference.md)
-
 ## License
 QtPromise is available under the [MIT license](https://github.com/simonbrunel/qtpromise/blob/master/LICENSE).

docs/SUMMARY.md

@@ -1,29 +0,0 @@
-### QtPromise for C++
-* [Getting Started](qtpromise/getting-started.md)
-* [QtConcurrent](qtpromise/qtconcurrent.md)
-* [Thread-Safety](qtpromise/thread-safety.md)
-* [API Reference](qtpromise/api-reference.md)
-  * [QPromise](qtpromise/qpromise/constructor.md)
-  * [.delay](qtpromise/qpromise/delay.md)
-  * [.each](qtpromise/qpromise/each.md)
-  * [.fail](qtpromise/qpromise/fail.md)
-  * [.filter](qtpromise/qpromise/filter.md)
-  * [.finally](qtpromise/qpromise/finally.md)
-  * [.isFulfilled](qtpromise/qpromise/isfulfilled.md)
-  * [.isPending](qtpromise/qpromise/ispending.md)
-  * [.isRejected](qtpromise/qpromise/isrejected.md)
-  * [.map](qtpromise/qpromise/map.md)
-  * [.tap](qtpromise/qpromise/tap.md)
-  * [.tapFail](qtpromise/qpromise/tapfail.md)
-  * [.then](qtpromise/qpromise/then.md)
-  * [.timeout](qtpromise/qpromise/timeout.md)
-  * [.wait](qtpromise/qpromise/wait.md)
-  * [::all (static)](qtpromise/qpromise/all.md)
-  * [::reject (static)](qtpromise/qpromise/reject.md)
-  * [::resolve (static)](qtpromise/qpromise/resolve.md)
-  * [qPromise](qtpromise/helpers/qpromise.md)
-  * [qPromiseAll](qtpromise/helpers/qpromiseall.md)
-  * [QtPromise::attempt](qtpromise/helpers/attempt.md)
-  * [QtPromise::each](qtpromise/helpers/each.md)
-  * [QtPromise::filter](qtpromise/helpers/filter.md)
-  * [QtPromise::map](qtpromise/helpers/map.md)

docs/assets/style.css

@@ -1,15 +0,0 @@
-a.anchorjs-link {
-    color: rgba(65, 131, 196, 0.1);
-    font-weight: 400;
-    text-decoration: none;
-    transition: color 100ms ease-out;
-    z-index: 999;
-}
-
-a.anchorjs-link:hover {
-    color: rgba(65, 131, 196, 1);
-}
-
-sup {
-    font-size: 0.75em !important;
-}

docs/qtpromise/api-reference.md

@@ -1,6 +1,6 @@
-## QPromise
+# API Reference
 
-### Public Members
+## Functions
 
 * [`QPromise<T>::QPromise`](qpromise/constructor.md)
 * [`QPromise<T>::delay`](qpromise/delay.md)
@@ -18,7 +18,7 @@
 * [`QPromise<T>::timeout`](qpromise/timeout.md)
 * [`QPromise<T>::wait`](qpromise/wait.md)
 
-### Public Static Members
+## Static Functions
 
 * [`[static] QPromise<T>::all`](qpromise/all.md)
 * [`[static] QPromise<T>::reject`](qpromise/reject.md)
@@ -26,9 +26,9 @@
 
 ## Helpers
 
-* [`qPromise`](helpers/qpromise.md)
-* [`qPromiseAll`](helpers/qpromiseall.md)
 * [`QtPromise::attempt`](helpers/attempt.md)
 * [`QtPromise::each`](helpers/each.md)
 * [`QtPromise::filter`](helpers/filter.md)
 * [`QtPromise::map`](helpers/map.md)
+* [`qPromise`](helpers/qpromise.md)
+* [`qPromiseAll`](helpers/qpromiseall.md)

docs/qtpromise/getting-started.md

@@ -1,8 +1,10 @@
+# Getting Started
+
 ## 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`.
 
-## qpm
+### qpm
 
 Alternatively and **only** if your project relies on [qpm](https://www.qpm.io/), you can install QtPromise as follow:
 

docs/qtpromise/helpers/attempt.md

@@ -1,4 +1,10 @@
-## `QtPromise::attempt`
+---
+title: attempt
+---
+
+# QtPromise::attempt
+
+*Since: 0.4.0*
 
 ```cpp
 QtPromise::attempt(Functor functor, Args...) -> QPromise<R>

docs/qtpromise/helpers/each.md

@@ -1,4 +1,10 @@
-## `QtPromise::each`
+---
+title: each
+---
+
+# QtPromise::each
+
+*Since: 0.4.0*
 
 ```cpp
 QtPromise::each(Sequence<T> values, Functor functor) -> QPromise<Sequence<T>>

docs/qtpromise/helpers/filter.md

@@ -1,4 +1,10 @@
-## `QtPromise::filter`
+---
+title: filter
+---
+
+# QtPromise::filter
+
+*Since: 0.4.0*
 
 ```cpp
 QtPromise::filter(Sequence<T> values, Filterer filterer) -> QPromise<Sequence<T>>
@@ -38,7 +44,9 @@ output.then([](const QVector<QUrl>& res) {
 });
 ```
 
-> **Note:** the order of the output sequence values is guarantee to be the same as the original
+::: tip NOTE
+The order of the output sequence values is guarantee to be the same as the original
 sequence, regardless of completion order of the promises returned by `filterer`.
+:::
 
 See also: [`QPromise<T>::filter`](../qpromise/filter.md)

docs/qtpromise/helpers/map.md

@@ -1,4 +1,10 @@
-## `QtPromise::map`
+---
+title: map
+---
+
+# QtPromise::map
+
+*Since: 0.4.0*
 
 ```cpp
 QtPromise::map(Sequence<T> values, Mapper mapper) -> QPromise<QVector<R>>
@@ -37,7 +43,9 @@ output.then([](const QVector<QByteArray>& res) {
 });
 ```
 
-> **Note:** the order of the output sequence values is guarantee to be the same as the original
+::: tip NOTE
+The order of the output sequence values is guarantee to be the same as the original
 sequence, regardless of completion order of the promises returned by `mapper`.
+:::
 
 See also: [`QPromise<T>::map`](../qpromise/map.md)

docs/qtpromise/helpers/qpromise.md

@@ -1,4 +1,10 @@
-## `qPromise`
+---
+title: qPromise
+---
+
+# qPromise
+
+*Since: 0.1.0*
 
 ```
 qPromise(T value) -> QPromise<R>

docs/qtpromise/helpers/qpromiseall.md

@@ -1,4 +1,10 @@
-## `qPromiseAll`
+---
+title: qPromiseAll
+---
+
+# qPromiseAll
+
+*Since: 0.1.0*
 
 ```
 qPromiseAll(Sequence<QPromise<T>> promises) -> QPromise<QVector<T>>

docs/qtpromise/qpromise/all.md

@@ -1,4 +1,10 @@
-## `[static] QPromise<T>::all`
+---
+title: ::all [static]
+---
+
+# QPromise::all [static]
+
+*Since: 0.1.0*
 
 ```
 [static] QPromise<T>::all(Sequence<QPromise<T>> promises) -> QPromise<QVector<T>>

docs/qtpromise/qpromise/constructor.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::QPromise`
+---
+title: constructor
+---
 
-```
+# QPromise::QPromise
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::QPromise(Function resolver)
 ```
 
@@ -18,7 +24,9 @@ QPromise<int> promise([](const QPromiseResolve<int>& resolve, const QPromiseReje
 });
 ```
 
-> **Note:** `QPromise<void>` is specialized to not contain any value, meaning that the `resolve` callback takes no argument.
+::: tip NOTE
+`QPromise<void>` is specialized to not contain any value, meaning that the `resolve` callback takes no argument.
+:::
 
 **C++14**
 

docs/qtpromise/qpromise/delay.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::delay`
+---
+title: .delay
+---
 
-```
+# QPromise::delay
+
+*Since: 0.2.0*
+
+```cpp
 QPromise<T>::delay(int msec) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/each.md

@@ -1,6 +1,10 @@
-## `QPromise<Sequence<T>>::each`
+---
+title: .each
+---
 
-> **Important:** applies only to promise with sequence value.
+# QPromise::each
+
+*Since: 0.4.0*
 
 ```cpp
 QPromise<Sequence<T>>::each(Functor functor) -> QPromise<Sequence<T>>
@@ -10,6 +14,10 @@ QPromise<Sequence<T>>::each(Functor functor) -> QPromise<Sequence<T>>
 // - Functor: Function(T value, int index) -> any
 ```
 
+::: warning IMPORTANT
+This method only applies to promise with sequence value.
+:::
+
 Calls the given `functor` on each element in the promise value (i.e. `Sequence<T>`), then resolves to the original sequence unmodified. If `functor` throws, `output` is rejected with the new exception.
 
 ```cpp

docs/qtpromise/qpromise/fail.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::fail`
+---
+title: .fail
+---
 
-```
+# QPromise::fail
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::fail(Function onRejected) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/filter.md

@@ -1,6 +1,10 @@
-## `QPromise<Sequence<T>>::filter`
+---
+title: .filter
+---
 
-> **Important:** applies only to promise with sequence value.
+# QPromise::filter
+
+*Since: 0.4.0*
 
 ```cpp
 QPromise<Sequence<T>>::filter(Filter filterer) -> QPromise<Sequence<T>>
@@ -10,6 +14,10 @@ QPromise<Sequence<T>>::filter(Filter filterer) -> QPromise<Sequence<T>>
 // - Filterer: Function(T value, int index) -> bool
 ```
 
+::: warning IMPORTANT
+This method only applies to promise with sequence value.
+:::
+
 Iterates over all the promise values (i.e. `Sequence<T>`) and [filters the sequence](https://en.wikipedia.org/wiki/Filter_%28higher-order_function%29)
 to another using the given `filterer` function. If `filterer` returns `true`, a copy of the item
 is put in the `output` sequence, otherwise, the item will not appear in  `output`. If `filterer`
@@ -39,7 +47,9 @@ output.then([](const QList<QUrl>& res) {
 });
 ```
 
-> **Note:** the order of the output sequence values is guarantee to be the same as the original
+::: tip NOTE
+The order of the output sequence values is guarantee to be the same as the original
 sequence, regardless of completion order of the promises returned by `filterer`.
+:::
 
 See also: [`QtPromise::filter`](../helpers/filter.md)

docs/qtpromise/qpromise/finally.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::finally`
+---
+title: .finally
+---
 
-```
+# QPromise::finally
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::finally(Function handler) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/isfulfilled.md

@@ -1,6 +1,12 @@
-# `QPromise<T>::isFulfilled`
+---
+title: .isFulfilled
+---
 
-```
+# QPromise::isFulfilled
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::isFulfilled() -> bool
 ```
 

docs/qtpromise/qpromise/ispending.md

@@ -1,6 +1,12 @@
-# `QPromise<T>::isPending`
+---
+title: .isPending
+---
 
-```
+# QPromise::isPending
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::isPending() -> bool
 ```
 

docs/qtpromise/qpromise/isrejected.md

@@ -1,6 +1,12 @@
-# `QPromise<T>::isRejected`
+---
+title: .isRejected
+---
 
-```
+# QPromise::isRejected
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::isRejected() -> bool
 ```
 

docs/qtpromise/qpromise/map.md

@@ -1,6 +1,10 @@
-## `QPromise<Sequence<T>>::map`
+---
+title: .map
+---
 
-> **Important:** applies only to promise with sequence value.
+# QPromise::map
+
+*Since: 0.4.0*
 
 ```cpp
 QPromise<Sequence<T>>::map(Mapper mapper) -> QPromise<QVector<R>>
@@ -10,6 +14,10 @@ QPromise<Sequence<T>>::map(Mapper mapper) -> QPromise<QVector<R>>
 // - Mapper: Function(T value, int index) -> R | QPromise<R>
 ```
 
+::: warning IMPORTANT
+This method only applies to promise with sequence value.
+:::
+
 Iterates over all the promise values (i.e. `Sequence<T>`) and [maps the sequence](https://en.wikipedia.org/wiki/Map_%28higher-order_function%29)
 to another using the given `mapper` function. The type returned by `mapper` determines the type
 of the `output` promise. If `mapper` throws, `output` is rejected with the new exception.
@@ -41,8 +49,10 @@ output.then([](const QVector<DownloadResult>& res) {
 });
 ```
 
-> **Note:** the order of the output sequence values is guarantee to be the same as the original
+::: tip NOTE
+The order of the output sequence values is guarantee to be the same as the original
 sequence, regardless of completion order of the promises returned by `mapper`.
+:::
 
 This function is provided for convenience and is similar to:
 

docs/qtpromise/qpromise/reject.md

@@ -1,6 +1,12 @@
-## `[static] QPromise<T>::reject`
+---
+title: ::reject [static]
+---
 
-```
+# QPromise::reject [static]
+
+*Since: 0.1.0*
+
+```cpp
 [static] QPromise<T>::reject(any reason) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/resolve.md

@@ -1,4 +1,10 @@
-## `[static] QPromise<T>::resolve`
+---
+title: ::resolve [static]
+---
+
+# QPromise::resolve [static]
+
+*Since: 0.1.0*
 
 ```
 [static] QPromise<T>::resolve(T value) -> QPromise<T>

docs/qtpromise/qpromise/tap.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::tap`
+---
+title: .tap
+---
 
-```
+# QPromise::tap
+
+*Since: 0.2.0*
+
+```cpp
 QPromise<T>::tap(Function handler) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/tapfail.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::tapFail`
+---
+title: .tapFail
+---
 
-```
+# QPromise::tapFail
+
+*Since: 0.4.0*
+
+```cpp
 QPromise<T>::tapFail(Function handler) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/then.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::then`
+---
+title: .then
+---
 
-```
+# QPromise::then
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::then(Function onFulfilled, Function onRejected) -> QPromise<R>
 QPromise<T>::then(Function onFulfilled) -> QPromise<R>
 ```
@@ -17,9 +23,11 @@ auto output = input.then([](int res) {
 });
 ```
 
-> **Note**: `onRejected` handler is optional, `output` will be rejected with the same reason as `input`.
+::: tip NOTE
-
+`onRejected` handler is optional, in which case `output` will be rejected with
-> **Note**: it's recommended to use the [`fail`](fail.md) shorthand to handle errors.
+the same reason as `input`. Also note that it's recommended to use the
+[`fail`](fail.md) shorthand to handle errors.
+:::
 
 The type `<R>` of the `output` promise depends on the return type of the `onFulfilled` handler:
 
@@ -35,7 +43,11 @@ output.then([](const QString& res) {
 });
 ```
 
-> **Note**: only `onFulfilled` can change the promise type, `onRejected` **must** return the same type as `onFulfilled`. That also means if `onFulfilled` is `nullptr`, `onRejected` must return the same type as the `input` promise.
+::: tip NOTE
+Only `onFulfilled` can change the promise type, `onRejected` **must** return the
+same type as `onFulfilled`. That also means if `onFulfilled` is `nullptr`,
+`onRejected` must return the same type as the `input` promise.
+:::
 
 ```cpp
 QPromise<int> input = ...

docs/qtpromise/qpromise/timeout.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::timeout`
+---
+title: .timeout
+---
 
-```
+# QPromise::timeout
+
+*Since: 0.2.0*
+
+```cpp
 QPromise<T>::timeout(int msec, any error = QPromiseTimeoutException) -> QPromise<T>
 ```
 

docs/qtpromise/qpromise/wait.md

@@ -1,6 +1,12 @@
-## `QPromise<T>::wait`
+---
+title: .wait
+---
 
-```
+# QPromise::wait
+
+*Since: 0.1.0*
+
+```cpp
 QPromise<T>::wait() -> QPromise<T>
 ```
 

docs/qtpromise/qtconcurrent.md

@@ -1,4 +1,4 @@
-## QtConcurrent
+# QtConcurrent
 
 QtPromise integrates with [QtConcurrent](https://doc.qt.io/qt-5/qtconcurrent-index.html) to make easy chaining QFuture with QPromise.
 

docs/qtpromise/thread-safety.md

@@ -1,5 +1,7 @@
-## Thread-Safety
+# Thread-Safety
 
 QPromise is thread-safe and can be copied and accessed across different threads. QPromise relies on [explicitly data sharing](https://doc.qt.io/qt-5/qexplicitlyshareddatapointer.html#details) and thus `auto p2 = p1` represents the same promise: when `p1` resolves, handlers registered on `p1` and `p2` are called, the fulfilled value being shared between both instances.
 
-> **Note:** while it's safe to access the resolved value from different threads using [`then`](qpromise/then.md), QPromise provides no guarantee about the object being pointed to. Thread-safety and reentrancy rules for that object still apply.
+::: warning IMPORTANT
+While it's safe to access the resolved value from different threads using [`then`](qpromise/then.md), QPromise provides no guarantee about the object being pointed to. Thread-safety and reentrancy rules for that object still apply.
+:::