doc: MrDocs reference

Author: chandryan

CMakeLists.txt

@@ -7,6 +7,7 @@ cmake_minimum_required(VERSION 3.12...3.16)
 
 project(boost_msm VERSION "${BOOST_SUPERPROJECT_VERSION}" LANGUAGES CXX)
 
+option(BOOST_MSM_BUILD_MRDOCS "Build the target for MrDocs" OFF)
 option(BOOST_MSM_TEST_NLOHMANN_JSON "Test serialization with nlohmann/json" OFF)
 
 add_library(boost_msm INTERFACE)
@@ -52,3 +53,8 @@ if(BUILD_TESTING AND EXISTS "${CMAKE_CURRENT_SOURCE_DIR}/test/CMakeLists.txt")
   enable_testing()
   add_subdirectory(test)
 endif()
+
+if(BOOST_MSM_BUILD_MRDOCS)
+  add_library(boost_msm_mrdocs ${CMAKE_CURRENT_SOURCE_DIR}/doc/mrdocs.cpp)
+  target_link_libraries(boost_msm_mrdocs boost_msm)
+endif()

doc/Makefile

@@ -2,7 +2,16 @@
 SOURCE:=$(shell find modules)
 
 build/lib/doc/robots.txt: $(SOURCE)
-	npx antora --fetch local-playbook.yml
+	npx antora --fetch local-playbook.yml --stacktrace
 
 .PHONY: build
 build : build/lib/doc/robots.txt
+
+.PHONY: setup
+setup:
+	npm install
+	wget -q https://github.com/cppalliance/mrdocs/releases/download/v0.8.0/MrDocs-0.8.0-Linux.tar.xz -O mrdocs.tar.xz
+	sudo tar -xJf mrdocs.tar.xz -C /usr/local --strip-components=1 MrDocs-0.8.0-Linux
+	rm mrdocs.tar.xz
+	git init && git commit --allow-empty -m init
+

doc/README.md

@@ -2,11 +2,13 @@
 
 Run the following commands once for the initial setup:
 
-- Make sure nodejs (>= 16.0.0) & npm are installed: `sudo apt install nodejs npm`
+- Make sure nodejs (LTS version >= 16.0.0) & npm are installed: `sudo apt install nodejs npm`
 - Make sure you are in the doc folder: `cd doc`
-- Install the required packages: `npm install`
-- Set up a pseudo-repository: `git init && git commit --allow-empty -m init`
+- Run the Make target for the setup: `make setup`
 
-Antora requires the doc sources to be located within a git repository, but it cannot recognize git submodules. By setting up a pseudo-repository in the doc folder, the local documentation build works when MSM is used as a standalone repo as well as when MSM is opened from a submodule path within the Boost super-project.
+The setup creates a pseudo-repository in the doc folder:
+Antora requires the doc sources to be located within a git repository, but it cannot recognize git submodules. By setting up a pseudo-repository, the local documentation build works when MSM is used as a standalone repo as well as when MSM is opened from a submodule path within the Boost super-project.
 
-After the initial setup is done, build the the documentation by running `npx antora --fetch local-playbook.yml` from the doc folder. Or use the Makefile, `make build`.
+After the initial setup is done, build the the documentation with `make build`.
+
+If you are not interested in viewing the generated API reference, you can speed up the documenation build with the ENV `ANTORA_SKIP_CPP_REFERENCE=1`.

doc/antora.yml

@@ -9,3 +9,6 @@ asciidoc:
     page-pagination: ''
     # Show an additional TOC on the right sidebar
     page-toc: ''
+ext:
+  cpp-reference:
+    config: doc/mrdocs.yml

doc/local-playbook.yml

@@ -53,13 +53,13 @@ antora:
         using-namespaces:
           - 'boost::'
     - require: '@cppalliance/antora-downloads-extension'
-    # - require: '@cppalliance/antora-cpp-reference-extension'
-    #   dependencies:
-    #     - name: 'boost'
-    #       repo: 'https://github.com/boostorg/boost.git'
-    #       tag: 'develop'
-    #       variable: 'BOOST_SRC_DIR'
-    #       system-env: 'BOOST_SRC_DIR'
+    - require: '@cppalliance/antora-cpp-reference-extension'
+      # dependencies:
+      #   - name: 'boost'
+      #     repo: 'https://github.com/boostorg/boost.git'
+      #     tag: 'develop'
+      #     variable: 'BOOST_SRC_DIR'
+      #     system-env: 'BOOST_SRC_DIR'
 
 asciidoc:
   attributes:

doc/modules/ROOT/pages/reference.adoc

@@ -1 +1,7 @@
 = Reference
+
+The following pages describe the API provided by MSM's components. 
+
+== External references to MSM
+
+An interesting mapping UML <-> MSM from Takatoshi Kondo can be found at http://redboltz.wikidot.com/boost-msm-guide[Redboltz].

doc/modules/ROOT/pages/reference/euml-operators-and-basic-helpers.adoc

@@ -2,6 +2,14 @@
 
 = eUML operators and basic helpers
 
+To use these functions, you need to include:
+
+[source,cpp]
+----
+#include <msm/front/euml/euml.hpp>
+----
+
+
 .eUML operators and basic helpers
 [cols="1,2,1",options="header"]
 |===
@@ -188,10 +196,3 @@
 |Returns (as reference) the state state_name referenced in the current state machine or the one given as argument.
 |`SubState_`
 |===
-
-To use these functions, you need to include:
-
-[source,cpp]
-----
-#include <msm/front/euml/euml.hpp>
-----