added generate-diagram option & cache

CMakeLists.txt

@@ -100,7 +100,7 @@ else()
 
     file(GLOB_RECURSE ADOC_FILES RELATIVE ${CMAKE_CURRENT_SOURCE_DIR} *.adoc)
     add_custom_command(OUTPUT ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html
-                       COMMAND asciidoctor ${CMAKE_CURRENT_SOURCE_DIR}/doc/index.adoc --require asciidoctor-diagram --require asciidoctor-multipage -b multipage_html5  -o ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html
+                       COMMAND asciidoctor ${CMAKE_CURRENT_SOURCE_DIR}/doc/index.adoc --require asciidoctor-diagram --require asciidoctor-multipage -b multipage_html5 -a generate-diagram -o ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html
                        DEPENDS ${ADOC_FILES})
 
     add_custom_target(boost_cobalt_doc DEPENDS  ${CMAKE_CURRENT_BINARY_DIR}/doc/index.html)

doc/Jamfile

@@ -4,7 +4,7 @@
 
 import asciidoctor ;
 
-html index.html : index.adoc : <flags>"-r asciidoctor-diagram" ;
+html index.html : index.adoc  ;
 
 install html_ : index.html : <location>html ;
 

doc/background/lazy_eager.adoc

@@ -37,8 +37,8 @@ Coro Done
 resumed twice
 ----
 
-
-[mermaid]
+ifdef::generate-diagram[]
+[mermaid, target=lazy_eager1]
 ----
 sequenceDiagram
     participant main;
@@ -54,6 +54,11 @@ sequenceDiagram
     lazy->>main: co_return
     Note left of main: "resumed twice"
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/lazy_eager1.png[]
+endif::[]
 
 
 Whereas an eager coro would look like this:
@@ -90,8 +95,8 @@ Coro Done
 ----
 
 
-
-[mermaid]
+ifdef::generate-diagram[]
+[mermaid, target=lazy_eager2]
 ----
 sequenceDiagram
     participant main;
@@ -104,5 +109,9 @@ sequenceDiagram
     Note right of lazy: "Coro done"
     lazy->>main: co_return
     Note left of main: "resumed once"
+----
+endif::[]
 
-----
+ifndef::generate-diagram[]
+image::{docdir}/images/lazy_eager2.png[]
+endif::[]

doc/background/stackless.adoc

@@ -30,14 +30,20 @@ main()
     bar()
 ----
 
-[mermaid]
+ifdef::generate-diagram[]
+[mermaid, target=stackless1]
 ----
 sequenceDiagram
     main->>+foo: call
     foo->>+bar: call
     bar->>-foo: return
     foo->>-main: return
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/stackless1.png[]
+endif::[]
 
 Coroutines can be implemented a stackful, which means that it allocates a fixes chunk of memory and stacks function frames similar to a thread.
 C++20 coroutines are stackless, i.e. they only allocate their own frame and use the callers stack on resumption. Using our previous example:
@@ -75,7 +81,9 @@ main()
   f$example()
 ----
 
-[mermaid]
+
+ifdef::generate-diagram[]
+[mermaid, target=stackless2]
 ----
 sequenceDiagram
     participant main
@@ -89,5 +97,10 @@ sequenceDiagram
     main-->>example: resume
     example->>-main: co_return
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/stackless2.png[]
+endif::[]
 
 The same applies if a coroutine gets moved accross threads.

doc/index.adoc

@@ -11,6 +11,7 @@ Version 0.1, 29.01.2023
 :source-language: c++
 :example-caption: Example
 
+:imagesdir: {docdir}/images
 
 :leveloffset: +1
 

doc/primer/awaitables.adoc

@@ -19,15 +19,20 @@ NOTE: Type will be implicitly converted into an awaitable if there is an `operat
 This documentation will use `awaitable` to include these types,
 and "actual_awaitable" to refer to type conforming to the above prototype.
 
-
-[mermaid]
+ifdef::generate-diagram[]
+[mermaid, target=awaitables]
 ----
 flowchart TD
     aw{await_ready?}
     aw ---->|true| ar[await_resume]
     aw -->|false| as[await_suspend]
     as -->|Resume| ar
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/awaitables.png[]
+endif::[]
 
 In a `co_await` expression the waiting coroutine will first invoke
 `await_ready` to check if the coroutine needs to suspend.

doc/reference/generators.adoc

@@ -33,7 +33,9 @@ Which will generate the following output
  In coro 3
  In main 4
 
-[mermaid]
+
+ifdef::generate-diagram[]
+[mermaid, target=generators1]
 ----
 sequenceDiagram
     participant main;
@@ -47,6 +49,11 @@ sequenceDiagram
     example->>main: co_return 3
     Note left of main: "In main 4"
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/generators1.png[]
+endif::[]
 
 Values can be pushed into the generator, when `Push` (the second template parameter) is set to non-void:
 
@@ -117,7 +124,8 @@ Which will generate the following output
  In coro 3
  In main 4
 
-[mermaid]
+ifdef::generate-diagram[]
+[mermaid, target=generators2]
 ----
 sequenceDiagram
     participant main;
@@ -131,6 +139,11 @@ sequenceDiagram
     example->>main: co_return 3
     Note left of main: "In main 4"
 ----
+endif::[]
+
+ifndef::generate-diagram[]
+image::{docdir}/images/generators2.png[]
+endif::[]
 
 [#generator-executor]
 === Executor