doc, new style

dev/mdgen.py

@@ -1,3 +1,4 @@
+import glob
 import json
 from pathlib import Path
 import re
@@ -9,42 +10,44 @@ def split_list(text):
 
 
 hrefs = {"home": "/README.md", "reference": "/reference/README.md"}
-
-cpps = set()
-for ref in (Path(__file__).parent.parent / "reference.in").iterdir():
-    if ref.suffix == ".cpp" or (ref.suffix == ".md" and ref.stem not in cpps):
-        cpps.add(ref.stem)
-        md_path = ref.with_suffix(".md").name.replace("reference.in", "reference")
-        hrefs[ref.stem] = f"/reference/{md_path}"
-        with open(ref) as rh:
-            for text in rh.readlines():
-                if "---" in text:
-                    break
-                m = re.match(r"^entry: +(.*)", text)
-                if m:
-                    for symbol in split_list(m[1]):
-                        symbol = symbol.strip().replace("yorel::yomm2::", "")
-                        if symbol != ref.stem:
-                            hrefs[symbol] = f"/reference/{md_path}"
-                if m := re.search(r"hrefs: *([\w_-]+)", text):
-                    for href in split_list(m.group(1)):
-                        hrefs[href] = f"/reference/{md_path}"
+in_path = Path(__file__).parent.parent / "reference.in"
+in_files = list(
+    Path(ref_str)
+    for ref_str in sorted(
+    glob.glob("**/*.md", root_dir=in_path, recursive=True)
+    + glob.glob("**/*.cpp", root_dir=in_path, recursive=True), key=str.lower)
+)
+
+for ref in in_files:
+    md_path = str(ref.with_suffix(".md")).replace("reference.in", "reference")
+    hrefs[str(ref.with_suffix(""))] = f"/reference/{md_path}"
+    with open(in_path / ref) as rh:
+        for text in rh.readlines():
+            if "---" in text:
+                break
+            m = re.match(r"^entry: +(.*)", text)
+            if m:
+                for symbol in split_list(m[1]):
+                    symbol = symbol.strip().replace("yorel::yomm2::", "")
+                    if symbol != ref.stem:
+                        hrefs[symbol] = f"/reference/{md_path}"
+            if m := re.search(r"hrefs: *([\w_-]+)", text):
+                for href in split_list(m.group(1)):
+                    hrefs[href] = f"/reference/{md_path}"
 
 with open(".hrefs", "w", encoding="ascii") as fh:
     json.dump(hrefs, fh, indent=4)
 
-
 def replace_links(text):
     def sub(m):
-        text = m.group(1)
-        symbol = text.replace("`", "")
-        target = hrefs.get(symbol)
+        path = m.group(2)
+        target = hrefs.get(path.replace("::", "/"))
         if target is None:
-            print("POSSIBLY BROKEN:", symbol, file=sys.stderr)
-            return f"->{text}"
-        return f"[{text}]({target})"
+            print("POSSIBLY BROKEN:", path, file=sys.stderr)
+            return f"->{path}"
+        return f"[{m.group(1)}{path.split('/')[-1]}{m.group(3)}]({target})"
 
-    return re.sub(r"->(`?[\w_-]+`?)", sub, text)
+    return re.sub(r"->(`?)([/:\w_\-]+)(`?)", sub, text)
 
 
 def replace_md(text):

reference.in/boilerplate/code.md → reference.boilerplate/class.cpp

@@ -1,16 +1,16 @@
-#define BOOST_TEST_MODULE ENTITY
+#define BOOST_TEST_MODULE CLASS
 #include <boost/test/included/unit_test.hpp>
 
 /***
 
 <sub>/ ->home / ->reference </sub>
 
-entry: yorel::yomm2::ENTITY
+entry: yorel::yomm2::CLASS
 headers: yorel/yomm2/core.hpp, yorel/yomm2/keywords.hpp
 
 ---
 ```
-struct ENTITY;
+struct CLASS;
 ```
 
 TODO

reference.boilerplate/class.md

@@ -0,0 +1,35 @@
+<sub>/ ->home / ->reference / ->CLASS </sub>
+
+# yorel::yomm2::**CLASS**
+<br><small>Defined in header yorel/yomm2/core.hpp</small>
+```
+template<class TP>
+struct CLASS;
+```
+
+---
+
+TODO
+
+**Template parameters**
+
+**TP** - TP
+
+**Member functions**
+|      |      |
+| ---- | ---- |
+| TODO | TODO |
+| TODO | TODO |
+
+**Example**
+
+#include <yorel/yomm2/keywords.hpp>
+
+```c++
+// for brevity
+using namespace yorel::yomm2;
+
+BOOST_AUTO_TEST_CASE(ref_TODO) {
+    TODO
+}
+```

reference.boilerplate/member.md

@@ -0,0 +1,36 @@
+<sub>/ ->home / ->reference / ->CLASS / ->MEMBER </sub>
+
+# yorel::yomm2::CLASS::**MEMBER**
+
+---
+```
+CLASS::MEMBER;
+```
+
+TODO
+
+**Parameters**
+
+**TODO** - TODO.
+
+**Return value**
+
+TODO.
+
+**Errors**
+
+* TODO
+
+
+**Example**
+
+```c++
+#include <yorel/yomm2/keywords.hpp>
+
+// for brevity
+using namespace yorel::yomm2;
+
+BOOST_AUTO_TEST_CASE(ref_TODO) {
+    TODO
+}
+```

reference.in/CMakeLists.txt

@@ -30,16 +30,18 @@ foreach(cpp ${cpps})
 endforeach()
 
 if(${YOMM2_ENABLE_DOC})
-    file(GLOB mds "*.md")
+    file(GLOB_RECURSE MDs "*.md")
+    message(STATUS "${MDs}")
 
-    foreach(md ${mds})
-        string(REPLACE "reference.in" "reference" md_out "${md}")
+    foreach(MD ${MDs})
+        string(REPLACE "reference.in" "reference" MD_out "${MD}")
         add_custom_command(
-            OUTPUT "${md_out}"
-            COMMAND ${CMAKE_SOURCE_DIR}/dev/md2md "${md}" "${md_out}"
-            DEPENDS "${md};${code_deps}")
-        list(APPEND entries "${md_out}")
-    endforeach()
-
-    add_custom_target(reference ALL DEPENDS "${entries}")
+            OUTPUT "${MD_out}"
+            COMMAND ${CMAKE_SOURCE_DIR}/dev/md2md "${MD}" "${MD_out}"
+            DEPENDS "${MD};${code_deps}")
+        list(APPEND entries "${MD_out}")
+        message(STATUS "${MD_out}")
+        endforeach()
+
+    add_custom_target(reference DEPENDS "${entries}")
 endif()

reference.in/vectored_error.md

@@ -1,20 +1,19 @@
-<sub>/ ->home / ->reference </sub>
-
-**yorel::yomm2::vectored_error**<br>
-<sub>defined in <yorel/yomm2/core.hpp>, also provided by<yorel/yomm2/keywords.hpp></sub>
-
----
+<sub>/ ->home / ->reference / ->vectored_error </sub>
 
+# yorel::yomm2::**vectored_error**
+<small>Defined in header yorel/yomm2/core.hpp</small>
 ```
 template<class Policy>
 struct vectored_error;
 ```
 
+---
+
 `vectored_error` is an implementation of ->`error_handler` that provides an
-`error` static `std::function` member. Its default value prints diagnostics
-using the `error_output` facet, if present. Since it returns normally, the
-program is aborted by the caller. `error` can be set to a different function,
-which can `throw` to prevent program termination.
+`error` static `std::function` member. It is initialized to a function that
+prints diagnostics using the `error_output` facet, if present. Since it returns
+normally, the program is aborted by the caller. `error` can be set to a
+different function, which can `throw` to prevent program termination.
 
 ## Interactions with other facets
 
@@ -24,30 +23,14 @@ which can `throw` to prevent program termination.
 
 **Policy** - the policy containing the facet.
 
-## Members
-
-| static member variables             |                                  |
-| ----------------------------------- | -------------------------------- |
-| error                               | throw value contained in variant |
-| static member functions             |                                  |
-| default_error_handler               | print diagnostics                |
-
-### error
-
-```c++
-static void error(const error_type& error_variant);
-```
-
-Extract the value of `error_variant`, and throw it as an exception.
-
-#### Parameters
-
-**error_variant** - A variant containing an instance of a subclass of `error`.
-
-#### Return value
+## Static member functions
 
-None.
+|                       |                                  |
+| --------------------- | -------------------------------- |
+| default_error_handler | print diagnostics                |
 
-#### Errors
+## Static member variables
 
-None.
+|       |                                  |
+| ----- | -------------------------------- |
+| error | throw value contained in variant |

reference.in/vectored_error/default_error_handler.md

@@ -0,0 +1,19 @@
+<sub>/ ->home / ->reference / ->vectored_error / ->vectored_error/default_error_handler </sub>
+
+# vectored_error<Policy>::**default_error_handler**
+
+---
+```
+static void default_error_handler(const error_type& err);
+```
+
+If ->`error_output` is available in `Policy`, use it to print a description of
+`err`. Return normally, causing the program to be aborted by the caller.
+
+**Parameters**
+
+**err** - the variant containing the error.
+
+**Return value**
+
+(none)

reference.in/vectored_error/error.md

@@ -0,0 +1,13 @@
+<sub>/ ->home / ->reference / ->vectored_error / ->vectored_error/error </sub>
+
+# vectored_error<Policy>::**error**
+
+---
+```
+static error_handler_type error = ;
+```
+
+A `std::function` containing a error handler. It is set to
+->`vectored_error::default_error_handler`
+
+Can be set to a user-provided handler.