More documentation work. Prepping to deploy.

stlab · Jun 6, 2024 · 0182b59 · 0182b59
1 parent ea9fb56
commit 0182b59
Show file tree

Hide file tree

Showing 275 changed files with 359 additions and 1,076 deletions.
diff --git a/docs/Gemfile b/docs/Gemfile
@@ -3,6 +3,7 @@ gem 'jekyll'
 gem 'jekyll-redirect-from', group: [:jekyll_plugins]
 gem 'jekyll-compose', group: [:jekyll_plugins]
 gem "jekyll-remote-theme", group: [:jekyll_plugins]
+
 # don't submit this line to the upstream repo
 ## Enable this line for local theme development
 # gem 'jekyll-theme-adobe-hyde', path: '../../themes'
diff --git a/docs/Gemfile.lock b/docs/Gemfile.lock
@@ -1,3 +1,10 @@
+PATH
+  remote: ../../themes
+  specs:
+    jekyll-theme-adobe-hyde (2.0.2)
+      jekyll (~> 4.3)
+      jekyll-seo-tag (~> 2.0)
+
 GEM
   remote: https://rubygems.org/
   specs:
@@ -60,6 +67,8 @@ GEM
       rubyzip (>= 1.3.0, < 3.0)
     jekyll-sass-converter (3.0.0)
       sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
     jekyll-watch (2.2.1)
       listen (~> 3.0)
     kramdown (2.4.0)
@@ -165,6 +174,7 @@ DEPENDENCIES
   jekyll-compose
   jekyll-redirect-from
   jekyll-remote-theme
+  jekyll-theme-adobe-hyde!
 
 BUNDLED WITH
    2.5.11
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -10,37 +10,39 @@ title: stlab
 subtitle: modern, modular C++ algorithms and data structures.
 email: [email protected]
 description: > # this means to ignore newlines until "baseurl:"
-    stlab hosts modern, modular C++ algorithms and data structures.
+  stlab hosts modern, modular C++ algorithms and data structures.
 baseurl: "" # the subpath of your site, e.g. /blog
 url: "http://www.stlab.cc" # the base hostname & protocol for your site
 twitter_username: SeanParent
-github_username:  stlab
+github_username: stlab
 
 ## To build locally, toggle these two.
-remote_theme: adobe/[email protected].1
+remote_theme: adobe/[email protected].2
 # theme: jekyll-theme-adobe-hyde
+
 exclude:
-    - _source
-    - build
-    - stlab # from building examples
-    - boost # from building examples
-    - boost.tgz # from building examples
-    - "*.sh"
-    - README.md
-    - stlab.bbprojectd/
-    - vendor # For Travis-CI (see https://jekyllrb.com/docs/continuous-integration/)
-    - tools/
-    - bs-config.sj
-    - CMakeLists.txt
-    - Gemfile
-    - Gemfile.lock
+  - _source
+  - build
+  - boost # from building examples
+  - boost.tgz # from building examples
+  - "*.sh"
+  - README.md
+  - stlab.bbprojectd/
+  - vendor # For Travis-CI (see https://jekyllrb.com/docs/continuous-integration/)
+  - tools/
+  - bs-config.sj
+  - CMakeLists.txt
+  - Gemfile
+  - Gemfile.lock
 adobe_hyde:
-    header_image: stlab-logo-long.svg
+  header_image: stlab-logo-long.svg
+  hyde_yaml_dir: /includes
+  source_root: https://github.com/stlab/libraries/blob/main
 excerpt_separator: <!--more-->
 markdown: kramdown
 utterances:
-    repo: stlab/stlab.github.io
-    label: "utterance"
+  repo: stlab/stlab.github.io
+  label: "utterance"
 plugins:
   - jekyll-redirect-from
   - jekyll-remote-theme
diff --git a/docs/generate_docs.sh b/docs/generate_docs.sh
@@ -16,7 +16,6 @@ for CUR_FILE in ${SRC_FILE_SET}; do
     echo "Processing $CUR_FILE"
     CUR_COMMAND="hyde --access-filter-protected --namespace-blacklist=detail --hyde-update \"${CUR_FILE}\" --hyde-yaml-dir=${HYDE_DST_ROOT} --hyde-src-root=${SRC_ROOT} -- -std=c++20 -I${SRC_ROOT}/../build/hyde/ -I${SRC_ROOT}/"
 
-    # CUR_COMMAND="hyde --access-filter-protected --namespace-blacklist=detail --hyde-src-root=${SRC_ROOT} --hyde-yaml-dir=${HYDE_DST_ROOT} --hyde-update \"${CUR_FILE}\" -- -I${SRC_ROOT} -Wno-everything"
     echo $CUR_COMMAND
     eval $CUR_COMMAND
 done

diff --git a/docs/includes/index.md b/docs/includes/index.md
@@ -2,12 +2,12 @@
 layout: library
 title: includes
 hyde:
-  owner: fbrereto
-  brief: The `stlab` libraries.
+  owner: sean-parent
+  brief: Documentation and examples for the stlab libraries.
   tags:
     - library
   library-type: library
-  icon: __MISSING__
-  short_title: __OPTIONAL__
-  tab: __MISSING__
+  icon: book
+  short_title: Documentation
+  tab: Documentation
 ---
diff --git a/docs/includes/stlab/algorithm/reverse.hpp/f_reverse.md b/docs/includes/stlab/algorithm/reverse.hpp/f_reverse.md
@@ -2,13 +2,13 @@
 layout: function
 title: reverse
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __INLINED__
   tags:
     - function
   inline:
     brief:
-      - "***********************************************************************************************"
+      - Range-based `reverse`, will be deprecated in C++20 in favor of [`std::ranges::reverse`](https://en.cppreference.com/w/cpp/algorithm/ranges/reverse).
   defined_in_file: stlab/algorithm/reverse.hpp
   overloads:
     "template <class BidirectionalRange>\nvoid reverse(BidirectionalRange &)":
@@ -19,7 +19,7 @@ hyde:
       description: __INLINED__
       inline:
         description:
-          - "***********************************************************************************************"
+          - Range-based `reverse`, will be deprecated in C++20 in favor of [`std::ranges::reverse`](https://en.cppreference.com/w/cpp/algorithm/ranges/reverse).
       return: __OPTIONAL__
       signature_with_names: "template <class BidirectionalRange>\nvoid reverse(BidirectionalRange & range)"
   namespace:

diff --git a/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_append.md b/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_append.md
@@ -2,13 +2,12 @@
 layout: function
 title: reverse_append
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __INLINED__
   tags:
     - function
   inline:
-    brief:
-      - "***********************************************************************************************"
+    brief: _multiple descriptions_
   defined_in_file: stlab/algorithm/reverse.hpp
   overloads:
     "template <typename I>\nauto reverse_append(I, I, I) -> I":
@@ -20,25 +19,28 @@ hyde:
           name: last
           type: I
         - description: __OPTIONAL__
-          name: result
+          name: end
           type: I
-      description: __INLINED__
+      description: "`I` is a model of `forward_node_iterator`.\n"
       inline:
         description:
-          - "***********************************************************************************************"
+          - Reverses the range `[first, last)` and appends `end`. Returns the beginning of the reversed range such that `[result, end)` is a valid range.
       return: __OPTIONAL__
-      signature_with_names: "template <typename I>\nauto reverse_append(I first, I last, I result) -> I"
+      signature_with_names: "template <typename I>\nauto reverse_append(I first, I last, I end) -> I"
     "template <typename R, typename I>\nauto reverse_append(R &, I) -> I":
       arguments:
         - description: __OPTIONAL__
           name: range
           type: R &
         - description: __OPTIONAL__
-          name: result
+          name: end
           type: I
-      description: __MISSING__
+      description: "`R` is a model of `forward_node_range`. `I` is a model of `forward_node_iterator`.\n"
+      inline:
+        description:
+          - Reverses `range` and appends `end`.  Returns the beginning of the reversed range such that `[result, end)` is a valid range.
       return: __OPTIONAL__
-      signature_with_names: "template <typename R, typename I>\nauto reverse_append(R & range, I result) -> I"
+      signature_with_names: "template <typename R, typename I>\nauto reverse_append(R & range, I end) -> I"
   namespace:
     - stlab
     - unsafe

diff --git a/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_copy.md b/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_copy.md
@@ -2,10 +2,12 @@
 layout: function
 title: reverse_copy
 hyde:
-  owner: __MISSING__
-  brief: __MISSING__
+  owner: sean-parent
+  brief: __INLINED__
   tags:
     - function
+  inline:
+    brief: _multiple descriptions_
   defined_in_file: stlab/algorithm/reverse.hpp
   overloads:
     "template <class BidirectionalRange, class OutputIterator>\nvoid reverse_copy(BidirectionalRange &, OutputIterator)":
@@ -16,7 +18,10 @@ hyde:
         - description: __OPTIONAL__
           name: result
           type: OutputIterator
-      description: __MISSING__
+      description: __INLINED__
+      inline:
+        description:
+          - Range-based `reverse_copy` algorithm, will be deprecated in C++20 in favor of [`std::ranges::reverse_copy`](https://en.cppreference.com/w/cpp/algorithm/ranges/reverse_copy).
       return: __OPTIONAL__
       signature_with_names: "template <class BidirectionalRange, class OutputIterator>\nvoid reverse_copy(BidirectionalRange & range, OutputIterator result)"
     "template <class BidirectionalRange, class OutputIterator>\nvoid reverse_copy(const BidirectionalRange &, OutputIterator)":
@@ -27,7 +32,10 @@ hyde:
         - description: __OPTIONAL__
           name: result
           type: OutputIterator
-      description: __MISSING__
+      description: __INLINED__
+      inline:
+        description:
+          - Range-based `reverse_copy` algorithm, will be deprecated in C++20 in favor of [`std::ranges::reverse_copy`](https://en.cppreference.com/w/cpp/algorithm/ranges/reverse_copy).
       return: __OPTIONAL__
       signature_with_names: "template <class BidirectionalRange, class OutputIterator>\nvoid reverse_copy(const BidirectionalRange & range, OutputIterator result)"
   namespace:

diff --git a/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_nodes.md b/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_nodes.md
@@ -2,7 +2,7 @@
 layout: function
 title: reverse_nodes
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - function

diff --git a/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_until.md b/docs/includes/stlab/algorithm/reverse.hpp/f_reverse_until.md
@@ -2,13 +2,13 @@
 layout: function
 title: reverse_until
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __INLINED__
   tags:
     - function
   inline:
     brief:
-      - "***********************************************************************************************"
+      - Reverses the range `[f, l)` until `m` is reached. Returns a range [a, b) of the un-reversed subrange such that either `a == m` or `b == m`.
   defined_in_file: stlab/algorithm/reverse.hpp
   overloads:
     "template <typename I>\nauto reverse_until(I, I, I) -> std::pair<I, I>":
@@ -22,10 +22,10 @@ hyde:
         - description: __OPTIONAL__
           name: l
           type: I
-      description: __INLINED__
+      description: "`I` is a model of `std::bidirectional_iterator`.\n"
       inline:
         description:
-          - "***********************************************************************************************"
+          - Reverses the range `[f, l)` until `m` is reached. Returns a range [a, b) of the un-reversed subrange such that either `a == m` or `b == m`.
       return: __OPTIONAL__
       signature_with_names: "template <typename I>\nauto reverse_until(I f, I m, I l) -> std::pair<I, I>"
   namespace:

diff --git a/docs/includes/stlab/algorithm/reverse.hpp/index.md b/docs/includes/stlab/algorithm/reverse.hpp/index.md
@@ -2,7 +2,7 @@
 layout: library
 title: stlab/algorithm/reverse.hpp
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - sourcefile

diff --git a/docs/includes/stlab/concurrency/channel.hpp/argument_of3CR2028Arg293E/index.md b/docs/includes/stlab/concurrency/channel.hpp/argument_of3CR2028Arg293E/index.md
@@ -2,7 +2,7 @@
 layout: class
 title: argument_of<R (Arg)>
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - class

diff --git a/docs/includes/stlab/concurrency/channel.hpp/channel_error/index.md b/docs/includes/stlab/concurrency/channel.hpp/channel_error/index.md
@@ -2,7 +2,7 @@
 layout: class
 title: channel_error
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - class

diff --git a/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_channel_error.md b/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_channel_error.md
@@ -2,7 +2,7 @@
 layout: method
 title: channel_error
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __OPTIONAL__
   tags:
     - method

diff --git a/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_code.md b/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_code.md
@@ -2,7 +2,7 @@
 layout: method
 title: code
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - method

diff --git a/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_what.md b/docs/includes/stlab/concurrency/channel.hpp/channel_error/m_what.md
@@ -2,7 +2,7 @@
 layout: method
 title: what
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - method

diff --git a/docs/includes/stlab/concurrency/channel.hpp/f_for_each_n.md b/docs/includes/stlab/concurrency/channel.hpp/f_for_each_n.md
@@ -2,7 +2,7 @@
 layout: function
 title: for_each_n
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __INLINED__
   tags:
     - function

diff --git a/docs/includes/stlab/concurrency/channel.hpp/f_operator26.md b/docs/includes/stlab/concurrency/channel.hpp/f_operator26.md
@@ -2,7 +2,7 @@
 layout: function
 title: operator&
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - function

diff --git a/docs/includes/stlab/concurrency/channel.hpp/first_3CT12C20T3E/index.md b/docs/includes/stlab/concurrency/channel.hpp/first_3CT12C20T3E/index.md
@@ -2,7 +2,7 @@
 layout: class
 title: first_<T1, T>
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - class

diff --git a/...ncludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/index.md b/...ncludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/index.md
@@ -2,7 +2,7 @@
 layout: class
 title: function_process<R (Args...)>
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - class

diff --git a/...ludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/m_await.md b/...ludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/m_await.md
@@ -2,7 +2,7 @@
 layout: method
 title: await
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - method

diff --git a/...annel.hpp/function_process3CR2028.9cd1ac2f/m_function_process3CR2028Args293E.md b/...annel.hpp/function_process3CR2028.9cd1ac2f/m_function_process3CR2028Args293E.md
@@ -2,7 +2,7 @@
 layout: method
 title: function_process<R (Args...)>
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __OPTIONAL__
   tags:
     - method

diff --git a/...ludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/m_state.md b/...ludes/stlab/concurrency/channel.hpp/function_process3CR2028.9cd1ac2f/m_state.md
@@ -2,7 +2,7 @@
 layout: method
 title: state
 hyde:
-  owner: __MISSING__
+  owner: sean-parent
   brief: __MISSING__
   tags:
     - method