Merge pull request bemanproject#145 from steve-downey/mrdocs

Merge updated doc comments and support for mrdocs in addition to doxygen. 

* Add mrdocs configuration
* Support for using mrdocs to generate docs from code
* Cleanup more documentation
* Remove upgrade of packages from pip install
The new pip (24.3) has problems with older packages. Errors of the form
```
AttributeError: 'InstallRequirement' object has no attribute 'use_pep517'
```
That are unfixable from the user side.

Author: steve-downey

.gitignore

@@ -31,3 +31,4 @@ compile_commands.json
 
 /docs/html
 /docs/latex
+/docs/adoc/

Makefile

@@ -57,8 +57,16 @@ $(_build_path)/CMakeCache.txt: | $(_build_path) .gitmodules
 	-rm compile_commands.json
 	ln -s $(_build_path)/compile_commands.json
 
+$(_build_path)/compile_commands.json : $(_build_path)/CMakeCache.txt
+
+compile_commands.json: $(_build_path)/compile_commands.json
+	-rm compile_commands.json
+	ln -s $(_build_path)/compile_commands.json
+
 TARGET:=all
+compile: compile_commands.json
 compile: $(_build_path)/CMakeCache.txt ## Compile the project
+compile:  ## Compile the project
 	cmake --build $(_build_path)  --config $(CONFIG) --target all -- -k 0
 
 compile-headers: $(_build_path)/CMakeCache.txt ## Compile the headers
@@ -135,7 +143,7 @@ requirements-dev.txt: requirements-dev.in
 
 $(VENV):
 	$(PYEXECPATH) -m venv $(VENV)
-	$(PIP) install --upgrade pip setuptools wheel
+	$(PIP) install pip setuptools wheel
 	$(PIP) install pip-tools
 
 $(VENV)/$(MARKER): requirements.txt requirements-dev.txt | $(VENV)
@@ -178,6 +186,12 @@ view-coverage: ## View the coverage report
 docs: ## Build the docs with Doxygen
 	doxygen docs/Doxyfile
 
+.PHONY: mrdocs
+mrdocs: ## Build the docs with Doxygen
+	-rm -rf docs/adoc
+	cd docs && NO_COLOR=1 mrdocs mrdocs.yml 2>&1 | sed 's/\x1b\[[0-9;]*m//g'
+	find docs/adoc -name '*.adoc' | xargs asciidoctor
+
 # Help target
 .PHONY: help
 help: ## Show this help.

docs/mrdocs.yml

@@ -0,0 +1,24 @@
+# $schema: https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+# yaml-language-server: $schema=https://mrdocs.com/docs/mrdocs/develop/_attachments/mrdocs.schema.json
+
+---
+source-root: ..
+input:
+  - ../include
+exclude:
+  - ../include/beman/optional/detail
+exclude-patterns:
+  - ../include/beman/optional/detail/**
+  - ../tests/**
+  - ../examples/**
+includes:
+  - ../include
+file-patterns:
+  - '*.hpp'
+include-symbols:
+  - 'beman::optional::**'
+implementation-defined:
+  - 'beman::optional::detail'
+multipage: true
+generator: adoc
+output: adoc