From 41507cf47ea9f2ea65ad3d741db3933e5088e5c3 Mon Sep 17 00:00:00 2001 From: Sean Parent Date: Fri, 28 Jun 2024 19:22:18 -0700 Subject: [PATCH] Fixing conflicting docs on docs about how to generate the docs. I discovered we had two sets of conflicting docs about how to generate the docs. This is likely part of what has led to the documentation mess I'm cleaning up. Fixing... --- README.md | 21 ++++--------------- docs/README.md | 4 ++++ .../stlab/concurrency/await.hpp/index.md | 5 +---- validate_docs.sh | 6 +++++- 4 files changed, 14 insertions(+), 22 deletions(-) diff --git a/README.md b/README.md index 187d0454..572bb469 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ ASL libraries will be migrated here in the `stlab` namespace, new libraries will ### [Concurrency](https://www.stlab.cc/libraries/concurrency/) -This library provides futures and channels, high level abstractions for implementing algorithms that eases the use of multiple CPU cores while minimizing contention. This library solves several problems of the C++11 and C++17 TS futures. +This library provides futures and channels, high-level abstractions for implementing algorithms that ease the use of multiple CPU cores while minimizing contention. This library solves several problems of the C++11 and C++17 TS futures. ## Documentation @@ -58,7 +58,7 @@ cmake -S . -B ../BUILD -DCMAKE_BUILD_TYPE=# SEE BELOW but there are other options you may need to append in order to be successful. Among them: -- `-DCMAKE_BUILD_TYPE=`[`Release`|`Debug`] to build the given configuration (required unless you're using visual studio or another multi-config generator). +- `-DCMAKE_BUILD_TYPE=`[`Release`|`Debug`] to build the given configuration (required unless you're using Visual Studio or another multi-config generator). - `-DCMAKE_CXX_STANDARD=`[`17`|`20`|`23`] to build with compliance to the given C++ standard. - `-DBUILD_TESTING=OFF` if you only intend to build, but not test, this library. - `-DBoost_USE_STATIC_LIBS=TRUE` if you will be testing on Windows. @@ -101,21 +101,8 @@ or ctest -C Release ``` -depending on which configuration (`CMAKE_BUILD_TYPE`) you chose to build. +depending on which configuration (`CMAKE_BUILD_TYPE) you choose to build. ## Generating Documentation -STLab uses [hyde](https://github.com/adobe/hyde) to generate documentation boilerplate by scanning its public headers. You will need to follow Hyde's installation instructions and have `hyde` on your `$PATH` (detectable by `which hyde`). - -When adding a new public API, you should invoke - -``` -docker run --platform linux/x86_64 --mount type=bind,source="$(pwd)/..",target=/mnt/host --tty --interactive hyde bash -``` - -``` -cd /mnt/host/libraries -./validate_docs.sh --update -``` - -(or, simply `-u`) to generate the boilerplate for it. Then, fill in any fields marked as `__MISSING__`. Fields marked as `__OPTIONAL__` may be omitted. +For generating the documentation, see the [README.md](docs/README.md) in the `docs` directory. diff --git a/docs/README.md b/docs/README.md index a0b4861c..d6f1d9b7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,3 +89,7 @@ cd /mnt/host/libraries/docs ./generate_docs.sh ./about.sh ``` + +\[ this is from the old docs - need to update the docs and script. +> (or, simply `-u`) to generate the boilerplate for it. Then, fill in any fields marked as `__MISSING__`. Fields marked as `__OPTIONAL__` may be omitted. +\] diff --git a/docs/includes/stlab/concurrency/await.hpp/index.md b/docs/includes/stlab/concurrency/await.hpp/index.md index af0e3df9..145b8455 100644 --- a/docs/includes/stlab/concurrency/await.hpp/index.md +++ b/docs/includes/stlab/concurrency/await.hpp/index.md @@ -3,10 +3,7 @@ layout: library title: stlab/concurrency/await.hpp hyde: owner: sean-parent - brief: | - Await provides utilities to synchronously await the value from a `future` and to notify the default executor that a task is waiting. Blocking calls are discouraged because they may lead to deadlocks or thread explosions. - - There is a good presentation of the issues [here](https://youtu.be/Z86b3Rd09sE). + brief: "Await provides utilities to synchronously await the value from a `future` and to notify the default executor that a task is waiting. Blocking calls are discouraged because they may lead to deadlocks or thread explosions.\n\nThere is a good presentation of the issues [here](https://youtu.be/Z86b3Rd09sE).\n" tags: - sourcefile library-type: sourcefile diff --git a/validate_docs.sh b/validate_docs.sh index cafd0b1c..2f261cb1 100755 --- a/validate_docs.sh +++ b/validate_docs.sh @@ -1,5 +1,9 @@ #!/bin/bash +echo "This script is deprecated. Please use the new generate_docs.sh script instead." +echo "Keep this script temporarily until we move all the options into generate_docs." +exit 1 + # # This script invokes Hyde on the headers in the stlab directory. # Also see .hyde-config. @@ -118,7 +122,7 @@ then echo "$CMAKE_BUILD_DIR already exists. Please delete it or use -f." exit 1 else - cmake -S. -B $CMAKE_BUILD_DIR $CMAKE_ARGS + cmake --preset="hyde-build-docs" fi #