Introduce initial documentation (#13)

Singed-off-by: Daniil Dudkin <umarmungenfuerimmer@gmail.com>
Co-authored-by: Alexander Yurev <sapfir999999@yandex.ru>
Singed-off-by: Alexander Yurev <sapfir999999@yandex.ru>

.github/workflows/documentation.yml

@@ -0,0 +1,63 @@
+name: documentation
+
+on:
+  pull_request:
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+  push:
+    paths:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+    branches:
+      - master
+
+jobs:
+  checks:
+    if: github.event_name != 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/setup-node@v1
+        with:
+          node-version: '12.x'
+      - name: Test Build
+        run: |
+          cd documentation
+          if [ -e yarn.lock ]; then
+          yarn install --frozen-lockfile
+          elif [ -e package-lock.json ]; then
+          npm ci
+          else
+          npm i
+          fi
+          npm run build
+  gh-release:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v2.2.0
+        with:
+          node-version: '12.x'
+      - uses: webfactory/ssh-agent@v0.5.3
+        with:
+          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
+      - name: Release to GitHub Pages
+        env:
+          USE_SSH: true
+          GIT_USER: git
+        run: |
+          git config --global user.email "umarmungenfuerimmer@gmail.com"
+          git config --global user.name "Daniil Dudkin"
+          git push origin --delete gh-pages
+          git subtree push --prefix documentation origin gh-pages
+          git checkout gh-pages
+          if [ -e yarn.lock ]; then
+          yarn install --frozen-lockfile
+          elif [ -e package-lock.json ]; then
+          npm ci
+          else
+          npm i
+          fi
+          npm run deploy

.github/workflows/macos.yml

@@ -1,6 +1,14 @@
 name: macos
 
-on: [push, pull_request]
+on:
+  pull_request:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+  push:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
 
 jobs:
   build:
@@ -10,7 +18,7 @@ jobs:
       matrix:
         config:
           - { os: macos-10.15 }
-        build: [Debug, Release]
+        build: [ Debug, Release ]
 
     name: "${{matrix.config.os}}:${{matrix.build}}"
     steps:

.github/workflows/ubuntu.yml

@@ -1,30 +1,38 @@
 name: ubuntu
 
-on: [push, pull_request]
+on:
+  pull_request:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+  push:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
 
 jobs:
   ubuntu:
     runs-on: ubuntu-20.04
     strategy:
       fail-fast: false
       matrix:
-        build: [Debug, Release]
+        build: [ Debug, Release ]
         compiler:
-        - { cc: "gcc-9", cxx: "g++-9" }
-        - { cc: "gcc-10", cxx: "g++-10" }
-        - { cc: "clang-10", cxx: "clang++-10" }
-        - { cc: "clang-11", cxx: "clang++-11" }
-        - { cc: "clang-12", cxx: "clang++-12" }
+          - { cc: "gcc-9", cxx: "g++-9" }
+          - { cc: "gcc-10", cxx: "g++-10" }
+          - { cc: "clang-10", cxx: "clang++-10" }
+          - { cc: "clang-11", cxx: "clang++-11" }
+          - { cc: "clang-12", cxx: "clang++-12" }
 
     name: "${{matrix.compiler.cxx}}:${{matrix.build}}"
     steps:
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v2
 
-    - name: Configure CMake
-      run: cmake -DCMAKE_BUILD_TYPE=${{matrix.build}} -DCMAKE_C_COMPILER=${{matrix.compiler.cc}} -DCMAKE_CXX_COMPILER=${{matrix.compiler.cxx}}
+      - name: Configure CMake
+        run: cmake -DCMAKE_BUILD_TYPE=${{matrix.build}} -DCMAKE_C_COMPILER=${{matrix.compiler.cc}} -DCMAKE_CXX_COMPILER=${{matrix.compiler.cxx}}
 
-    - name: Build
-      run: cmake --build . --config ${{matrix.build}}
+      - name: Build
+        run: cmake --build . --config ${{matrix.build}}
 
-    - name: Tests
-      run: ctest --output-on-failure -C ${{matrix.build}}
+      - name: Tests
+        run: ctest --output-on-failure -C ${{matrix.build}}

.github/workflows/windows.yml

@@ -1,6 +1,14 @@
 name: windows
 
-on: [push, pull_request]
+on:
+  pull_request:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
+  push:
+    paths-ignore:
+      - 'documentation/**'
+      - '.github/workflows/documentation.yml'
 
 jobs:
   build:
@@ -9,20 +17,20 @@ jobs:
       fail-fast: false
       matrix:
         config:
-        - { os: windows-2016, vs: "Visual Studio 2017" } # https://github.com/actions/virtual-environments/blob/main/images/win/Windows2016-Readme.md#visual-studio-enterprise-2017
-        - { os: windows-2019, vs: "Visual Studio 2019" } # https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md#visual-studio-enterprise-2019
-        build: [Debug, Release]
-        platform: [Win32, x64]
+          - { os: windows-2016, vs: "Visual Studio 2017" } # https://github.com/actions/virtual-environments/blob/main/images/win/Windows2016-Readme.md#visual-studio-enterprise-2017
+          - { os: windows-2019, vs: "Visual Studio 2019" } # https://github.com/actions/virtual-environments/blob/main/images/win/Windows2019-Readme.md#visual-studio-enterprise-2019
+        build: [ Debug, Release ]
+        platform: [ Win32, x64 ]
 
     name: "${{matrix.config.vs}}:${{matrix.platform}}:${{matrix.build}}"
     steps:
-    - uses: actions/checkout@v2
+      - uses: actions/checkout@v2
 
-    - name: Configure CMake
-      run: cmake -A ${{matrix.platform}}
+      - name: Configure CMake
+        run: cmake -A ${{matrix.platform}}
 
-    - name: Build
-      run: cmake --build . --config ${{matrix.build}}
+      - name: Build
+        run: cmake --build . --config ${{matrix.build}}
 
-    - name: Tests
-      run: ctest --output-on-failure -C ${{matrix.build}}
+      - name: Tests
+        run: ctest --output-on-failure -C ${{matrix.build}}

documentation/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

documentation/README.md

@@ -0,0 +1,33 @@
+# Website
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

documentation/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

documentation/docs/about.md

@@ -0,0 +1,113 @@
+---
+sidebar_position: 1
+---
+
+# About
+
+This library provides `basic_fixed_string` class template to enable fixed-size `std::array` semantic with standard-like string semantic.
+
+## Features
+
+* C++17 or higher
+* Header-only
+* Dependency-free
+
+:::caution Warning
+Dependencies can be added later to enable lower C++ standards support.
+:::
+
+* No dynamic allocations
+* `constexpr` as much as possible
+* Can be used as class non-type template parameter *(since C++20)*
+
+## Possible usages
+
+* ## Make your own eDSL with C++20's class non-type template parameter feature
+
+[CTRE library](https://github.com/hanickadot/compile-time-regular-expressions) uses similar class to make regular expressions in C++ more easy to use:
+```cpp
+std::optional<std::string_view> extract_number(std::string_view s) noexcept {
+    if (auto m = ctre::match<"[a-z]+([0-9]+)">(s)) {
+        return m.get<1>().to_view();
+    } else {
+        return std::nullopt;
+    }
+}
+```
+
+* ## Make more concise APIs
+
+For example, before `fixed_string` if you needed to implement MD5 hash function, you'd write something like this:
+```cpp
+std::string hash_md5(std::string_view string);
+```
+This solution has 2 downsides: 
+* it can allocate
+* it can return a string that is not 16 bytes
+
+With `fixed_string` these 2 problems are solved:
+```cpp
+fixstr::fixed_string<16> hash_md5(std::string_view string);
+```
+
+* ## Use in a free-standing environment
+
+Returning to the example with the hash function: the implementation with `std::string` as the return type has one more downside which is a consequence of possible allocations - it cannot be used in free-standing environments where is no dynamic memory.
+
+## Examples
+
+* Construction
+```cpp
+constexpr fixstr::fixed_string foo = "foo";
+```
+
+* Concatenation
+```cpp
+using namespace fixstr;
+constexpr fixed_string first = "Hello, ";
+constexpr fixed_string second = "World!";
+constexpr auto result = first + second; // "Hello, World!"
+```
+
+* Comparison
+```cpp
+using namespace fixstr;
+constexpr fixed_string first = "Hello, ";
+constexpr fixed_string second = "World!";
+static_assert(first == second); // false
+static_assert(first != second); // true
+static_assert(first < second);  // true
+static_assert(first <= second); // true
+static_assert(first > second);  // false 
+static_assert(first >= second); // false
+static_assert(first <=> second != 0); // true
+```
+
+* Non-type template parameter
+```cpp
+template <fixstr::fixed_string Foo>
+void bar()
+{
+    static_assert(Foo == "foo"sv);
+}
+
+void foo()
+{
+    bar<"foo">();
+}
+```
+
+## Integration
+Since it's a header only library, you need just copy `fixed_string.hpp` to your project.
+
+If you are using [vcpkg](https://github.com/Microsoft/vcpkg/) on your project for external dependencies, then you can use the [**fixed-string** package](https://github.com/microsoft/vcpkg/tree/master/ports/fixed-string).
+
+If you are using Conan on your project for external dependencies, then you can use the Conan recipe located in the root of the repository.
+
+## Compiler compatibility
+* GCC >= 7.3
+* Clang >= 5
+* ICC >= 19.0.1
+* MSVC >= 14.28 / Visual Studio 2019 (I don't have access to older VS versions right now, so it can work on older versions too)
+
+**Using `basic_fixed_string` as class non-type template parameter full available in GCC >= 10 and VS 2019 16.9 or newer**

documentation/docs/api/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "API Reference",
+  "position": 2
+}