feat: support mkdocs integrating with mkdocs-material (#320)

* feat: support mkdocs integrating with mkdocs-material Signed-off-by: msclock <msclock@qq.com> * supplement docs generation for MkDocs Signed-off-by: msclock <msclock@qq.com> * fix docs requirements missing Signed-off-by: msclock <msclock@qq.com> * fix copier missing Signed-off-by: msclock <msclock@qq.com> * use default name Signed-off-by: msclock <msclock@qq.com> * set git user name and email for copier Signed-off-by: msclock <msclock@qq.com> * correct indentation between lines Signed-off-by: msclock <msclock@qq.com> * use default name for check-docs Signed-off-by: msclock <msclock@qq.com> --------- Signed-off-by: msclock <msclock@qq.com>
serious-scaffold · Jul 28, 2024 · 36aa100 · 36aa100
1 parent 7ce3c7d
commit 36aa100
Show file tree

Hide file tree

Showing 13 changed files with 447 additions and 23 deletions.
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -582,7 +582,6 @@ jobs:
 
 
   check-docs:
-    name: Docs build and checks
     runs-on: ubuntu-22.04
     needs: [pre-commit, consistency]
     timeout-minutes: 15
@@ -883,6 +882,64 @@ jobs:
       - name: Uninstall
         run: cmake --build --preset=default --target uninstall
 
+
+  check-mkdocs-docs:
+    runs-on: ubuntu-22.04
+    needs: [pre-commit, consistency]
+    timeout-minutes: 15
+
+    steps:
+      - uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Git
+        run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Cache
+        uses: actions/cache@0c45773b623bea8c8e75f6c82b208c3cf94ea4f9 # v4
+        with:
+          path: |
+            ~/vcpkg
+            ~/.cache/pip
+            ~/.cache/vcpkg
+          key: x64-linux-gcc-13-${{ hashFiles('vcpkg.json') }}
+          restore-keys: x64-linux-gcc-13-${{ hashFiles('vcpkg.json') }}
+
+      - uses: aminya/setup-cpp@v1
+        with:
+          compiler: gcc-13
+          cmake: true
+          ninja: true
+          ccache: true
+          doxygen: true
+          graphviz: true
+
+      - uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5
+        with:
+          python-version: 3.x
+
+      - name: Configure CMake
+        run: >
+          make cmake-configure CONFIGURE="
+          -DCMAKE_BUILD_TYPE=RelWithDebInfo
+          -DCMAKE_CXX_STANDARD=20
+          -DCMAKE_COMPILE_WARNING_AS_ERROR=ON
+          -DVCPKG_TARGET_TRIPLET=x64-linux
+          "
+
+      - name: Install copier
+        run: pipx install copier==9.3.1
+
+      - name: Apply mkdocs
+        run: make template-build COPIER_EXTRA_OPTS="-d docs_type=mkdocs"
+
+      - name: Checks the docs with warnings as errors
+        run: make docs-check
+
+
   pass:
     if: always()
     needs:
@@ -900,6 +957,7 @@ jobs:
       - check-auto-vcpkg-install
       - check-auto-detect-triplet
       - check-auto-build-type
+      - check-mkdocs-docs
     runs-on: ubuntu-22.04
     timeout-minutes: 2
     steps:

diff --git a/Makefile b/Makefile
@@ -1,4 +1,4 @@
-.PHONY: clean prerequisites pre-commit cmake-configure cmake-build cmake-test cmake-install cmake-uninstall test-build test-build-memcheck test-build-test test-build-test-install test-build-test-install-ccov test-coverage test-valgrind test-sanitizer-address test-sanitizer-leak test-sanitizer-memory test-sanitizer-undefined test-sanitizer test-cppcheck test-clang-tidy test-export-mode docs-doxygen docs-requirements docs docs-check docs-linkcheck template-watch template-build
+.PHONY: clean prerequisites pre-commit cmake-configure cmake-build cmake-test cmake-install cmake-uninstall test-build test-build-memcheck test-build-test test-build-test-install test-build-test-install-ccov test-coverage test-valgrind test-sanitizer-address test-sanitizer-leak test-sanitizer-memory test-sanitizer-undefined test-sanitizer test-cppcheck test-clang-tidy test-export-mode docs-clean docs-pip-requirements docs docs-check docs-serve docs-linkcheck template-watch template-build
 
 ########################################################################################
 # Variables
@@ -64,6 +64,8 @@ test-build: cmake-configure cmake-build
 
 test-build-memcheck: test-build cmake-build-template-ExperimentalMemCheck
 
+test-build-doxygen: cmake-configure cmake-build-template-ss-cpp-doxygen
+
 test-build-test: test-build cmake-test
 
 test-build-test-install: test-build-test cmake-install cmake-uninstall
@@ -102,14 +104,15 @@ test-export-mode:
 # Documentation
 ########################################################################################
 
-docs-doxygen:
-	$(MAKE) cmake-build-template-ss-cpp-doxygen
+docs-clean:
+	cmake -E rm -rf docs/_build/html
 
-docs-requirements: docs-doxygen
+docs-pip-requirements:
 	pip install -r docs/requirements.txt
 
-docs: docs-requirements
-	cmake -E rm -rf docs/_build/html
+docs-doxygen: cmake-build-template-ss-cpp-doxygen
+
+docs: docs-pip-requirements docs-doxygen docs-clean
 	sphinx-build -T $(SPHINX_EXTRA_OPTS) -c docs docs docs/_build/html
 
 docs-check:
@@ -118,6 +121,10 @@ docs-check:
 docs-linkcheck:
 	$(MAKE) docs SPHINX_EXTRA_OPTS="-b linkcheck $(SPHINX_EXTRA_OPTS)"
 
+docs-serve: docs-pip-requirements docs-doxygen docs-clean
+	python -m http.server --directory docs/_build/html &
+	watchfiles "make docs" docs src README.md LICENSE --ignore-paths docs/_build
+
 ########################################################################################
 # Template
 ########################################################################################
@@ -127,5 +134,5 @@ template-watch:
 
 template-build:
 	find . -maxdepth 1 | grep -vE '(\.|\.git|template|includes|copier\.yml)$$' | xargs -I {} rm -r {}
-	copier copy -r HEAD --data-file includes/copier-answers-sample.yml -f . .
+	copier copy -r HEAD --data-file includes/copier-answers-sample.yml $(COPIER_EXTRA_OPTS) -f . .
 	rm -rf .copier-answers.yml
diff --git a/README.md b/README.md
@@ -45,7 +45,7 @@ A continuously evolving basic template for cpp development.
 - Use [cmake-registry](https://github.com/msclock/cmake-registry) to provide various cmake modules and scripts.
 - Lint tool `pre-commit` integration with various linters, including [clang-format](https://github.com/pre-commit/mirrors-clang-format), [codespell](https://github.com/codespell-project/codespell), [markdownlint](https://github.com/igorshubovych/markdownlint-cli), and more.
 - Handy Makefile for local development.
-- Documentation generation with [doxygen](https://www.doxygen.nl/index.html) and [sphinx](https://www.sphinx-doc.org/en/master/) theme [furo](https://github.com/pradyunsg/furo).
+- Documentation generation with [sphinx](https://www.sphinx-doc.org/en/master/)[[furo](https://github.com/pradyunsg/furo)] or [mkdocs](https://www.mkdocs.org/)[[material](https://squidfunk.github.io/mkdocs-material/)].
 - Automatic release workflow with [semantic-release](https://github.com/semantic-release/semantic-release).
 - Maintainable [documentation](https://serious-scaffold.github.io/ss-cpp/) guides for configuration, development, security and contribution based on ss-cpp.
 

diff --git a/copier.yml b/copier.yml
@@ -1,5 +1,3 @@
-_exclude:
-  - includes
 _envops:
   block_end_string: '%]'
   block_start_string: '[%'
@@ -139,6 +137,7 @@ docs_type:
   default: sphinx
   choices:
     Sphinx: sphinx
+    MkDocs: mkdocs
   help: 'Choose the type of documentation to generate:'
   type: str
 

diff --git a/includes/variable.jinja b/includes/variable.jinja
@@ -22,6 +22,8 @@
 [% macro documentation_badge() -%]
   [% if docs_type == 'sphinx' -%]
 [![Documentation](https://img.shields.io/badge/Documentation-sphinx-blue)](https://{{ page_url() }})
+  [%- elif docs_type == 'mkdocs' -%]
+[![Documentation](https://img.shields.io/badge/Documentation-mkdocs-blue)](https://{{ page_url() }})
   [%- endif -%]
 [%- endmacro %]
 

diff --git a/template/Makefile.jinja b/template/Makefile.jinja
@@ -1,4 +1,5 @@
-.PHONY: clean prerequisites pre-commit cmake-configure cmake-build cmake-test cmake-install cmake-uninstall test-build test-build-memcheck test-build-test test-build-test-install test-build-test-install-ccov test-coverage test-valgrind test-sanitizer-address test-sanitizer-leak test-sanitizer-memory test-sanitizer-undefined test-sanitizer test-cppcheck test-clang-tidy test-export-mode docs-doxygen docs-requirements docs docs-check docs-linkcheck
+.PHONY: clean prerequisites pre-commit cmake-configure cmake-build cmake-test cmake-install cmake-uninstall test-build test-build-memcheck test-build-test test-build-test-install test-build-test-install-ccov test-coverage test-valgrind test-sanitizer-address test-sanitizer-leak test-sanitizer-memory test-sanitizer-undefined test-sanitizer test-cppcheck test-clang-tidy test-export-mode docs-clean docs-pip-requirements docs docs-check docs-serve
+[%- if docs_type == "sphinx" %] docs-linkcheck[% endif %]
 [%- if repo_name == "ss-cpp" %] template-watch template-build[% endif %]
 
 ########################################################################################
@@ -67,6 +68,8 @@ test-build: cmake-configure cmake-build
 
 test-build-memcheck: test-build cmake-build-template-ExperimentalMemCheck
 
+test-build-doxygen: cmake-configure cmake-build-template-{{ repo_name }}-doxygen
+
 test-build-test: test-build cmake-test
 
 test-build-test-install: test-build-test cmake-install cmake-uninstall
@@ -101,20 +104,23 @@ test-clang-tidy:
 [% if repo_name == "ss-cpp" -%]
 test-export-mode:
 	$(MAKE) test-build-test-install CONFIGURE="-DBUILD_TESTING=ON -DVCPKG_EXPORT_MODE=ON $(CONFIGURE)" FRESH_CMAKE_CACHE=1
-[%- endif %]
 
+[% endif -%]
 ########################################################################################
 # Documentation
 ########################################################################################
 
-docs-doxygen:
-	$(MAKE) cmake-build-template-{{ repo_name }}-doxygen
+docs-clean:
+	cmake -E rm -rf docs/_build/html
 
-docs-requirements: docs-doxygen
+docs-pip-requirements:
 	pip install -r docs/requirements.txt
 
-docs: docs-requirements
-	cmake -E rm -rf docs/_build/html
+[% if docs_type == "sphinx" -%]
+
+docs-doxygen: cmake-build-template-{{ repo_name }}-doxygen
+
+docs: docs-pip-requirements docs-doxygen docs-clean
 	sphinx-build -T $(SPHINX_EXTRA_OPTS) -c docs docs docs/_build/html
 
 docs-check:
@@ -123,7 +129,22 @@ docs-check:
 docs-linkcheck:
 	$(MAKE) docs SPHINX_EXTRA_OPTS="-b linkcheck $(SPHINX_EXTRA_OPTS)"
 
-[% if repo_name == "ss-cpp" -%]
+docs-serve: docs-pip-requirements docs-doxygen docs-clean
+	python -m http.server --directory docs/_build/html &
+	watchfiles "make docs" docs src README.md LICENSE --ignore-paths docs/_build
+[%- elif docs_type == "mkdocs" -%]
+
+docs: docs-pip-requirements
+	mkdocs build -d docs/_build/html $(MKDOCS_EXTRA_OPTS)
+
+docs-check:
+	$(MAKE) docs MKDOCS_EXTRA_OPTS="--strict $(MKDOCS_EXTRA_OPTS)"
+
+docs-serve: docs-pip-requirements
+	mkdocs serve $(MKDOCS_EXTRA_OPTS)
+[% endif -%]
+[%- if repo_name == "ss-cpp" %]
+
 ########################################################################################
 # Template
 ########################################################################################
@@ -133,6 +154,6 @@ template-watch:
 
 template-build:
 	find . -maxdepth 1 | grep -vE '(\.|\.git|template|includes|copier\.yml)$$' | xargs -I {} rm -r {}
-	copier copy -r HEAD --data-file includes/copier-answers-sample.yml -f . .
+	copier copy -r HEAD --data-file includes/copier-answers-sample.yml $(COPIER_EXTRA_OPTS) -f . .
 	rm -rf .copier-answers.yml
 [% endif -%]
diff --git a/template/README.md.jinja b/template/README.md.jinja
@@ -49,7 +49,7 @@
 - Use [cmake-registry](https://github.com/msclock/cmake-registry) to provide various cmake modules and scripts.
 - Lint tool `pre-commit` integration with various linters, including [clang-format](https://github.com/pre-commit/mirrors-clang-format), [codespell](https://github.com/codespell-project/codespell), [markdownlint](https://github.com/igorshubovych/markdownlint-cli), and more.
 - Handy Makefile for local development.
-- Documentation generation with [doxygen](https://www.doxygen.nl/index.html) and [sphinx](https://www.sphinx-doc.org/en/master/) theme [furo](https://github.com/pradyunsg/furo).
+- Documentation generation with [sphinx](https://www.sphinx-doc.org/en/master/)[[furo](https://github.com/pradyunsg/furo)] or [mkdocs](https://www.mkdocs.org/)[[material](https://squidfunk.github.io/mkdocs-material/)].
 - Automatic release workflow with [semantic-release](https://github.com/semantic-release/semantic-release).
 - Maintainable [documentation](https://serious-scaffold.github.io/ss-cpp/) guides for configuration, development, security and contribution based on ss-cpp.
 [%- else -%]

diff --git a/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/css/mkdocstrings.css b/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/css/mkdocstrings.css
@@ -0,0 +1,32 @@
+/* Indentation. */
+div.doc-contents:not(.first) {
+  padding-left: 25px;
+  border-left: .05rem solid var(--md-typeset-table-color);
+}
+
+/* Mark external links as such. */
+a.external::after,
+a.autorefs-external::after {
+  /* https://primer.style/octicons/arrow-up-right-24 */
+  mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  -webkit-mask-image: url('data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><path d="M18.25 15.5a.75.75 0 00.75-.75v-9a.75.75 0 00-.75-.75h-9a.75.75 0 000 1.5h7.19L6.22 16.72a.75.75 0 101.06 1.06L17.5 7.56v7.19c0 .414.336.75.75.75z"></path></svg>');
+  content: ' ';
+
+  display: inline-block;
+  vertical-align: middle;
+  position: relative;
+
+  height: 1em;
+  width: 1em;
+  background-color: var(--md-typeset-a-color);
+}
+
+a.external:hover::after,
+a.autorefs-external:hover::after {
+  background-color: var(--md-accent-fg-color);
+}
+
+/* Avoid breaking parameters name, etc. in table cells. */
+td code {
+  word-break: normal !important;
+}
diff --git a/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/includes/abbreviations.md b/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/includes/abbreviations.md
@@ -0,0 +1 @@
+<!-- *[abbreviations]: abbreviations definition. -->
diff --git a/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/index.md.jinja b/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/index.md.jinja
@@ -0,0 +1 @@
+--8<-- "README.md:1:"
diff --git a/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/requirements.txt b/template/[% if docs_type == 'mkdocs' %]docs[% endif %]/requirements.txt
@@ -0,0 +1,6 @@
+mkdocs==1.6.0
+mkdocs-material==9.5.29
+mkdocs-git-revision-date-localized-plugin==1.2.6
+mkdocs-same-dir==0.1.3
+mkdoxy==1.2.4
+mkdocs-minify-plugin==0.8.0