CI: Generate JavaScript docs

.github/workflows/build-test-distribute.yml

@@ -374,7 +374,7 @@ jobs:
     # !cancelled() need to ignore general fail previous job, because this job depends on one matrix variant (ubuntu 22),
     # and if this variant failed this job also will fail
     if: ${{ ( ( needs.config.outputs.upload_artifacts == 'true' && needs.config.outputs.build_enable_ubuntu_arm64 == 'true' ) || needs.config.outputs.update_doc == 'true' ) && !cancelled() }}
-    needs: [ config, generate-c-bindings ]
+    needs: [ config, ubuntu-arm64-build-test, generate-c-bindings ]
     uses: ./.github/workflows/update-docs.yml
     with:
       output_folder: MeshLib/dev

.github/workflows/build-test-emscripten.yml

@@ -211,6 +211,16 @@ jobs:
           MESHLIB_MODULE: build/Release/bin/${{ matrix.wasm-module-name }}.node.mjs
         run: node source/MRWasmTest/index.mjs
 
+        # Embind doesn't provide any way to define docstrings for the generated TypeScript definition file.
+        # `inject_tsdoc.py` manually updates it with docstrings extracted from the C++ code with Doxygen.
+        # The docstrings are then used both by the end users ("hover information") and for generating documentation.
+      - name: Document the TypeScript definition file
+        run: |
+          doxygen scripts/npm/Doxyfile
+          python3 scripts/npm/inject_tsdoc.py \
+            build/Release/bin/${{ matrix.wasm-module-name }}.d.mts \
+            --bindings source/MRWasmModule
+
       - name: Assemble and pack npm package
         run: |
           scripts/npm/assemble.sh ${{ matrix.wasm-module-name }} "${{ inputs.app_version }}"
@@ -232,6 +242,14 @@ jobs:
           path: js-meshlib-*.tgz
           retention-days: 1
 
+      - name: Upload the TypeScript definition file for docs
+        if: ${{ inputs.upload_artifacts && matrix.wasm-module-name == 'meshlib' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: WasmBindingsDts
+          path: npm-distr/meshlib/bindings.d.mts
+          retention-days: 1
+
   emscripten-test:
     needs: emscripten-build
     timeout-minutes: 10

.github/workflows/update-docs.yml

@@ -64,6 +64,13 @@ jobs:
           name: CsharpBindings
           path: MeshLib/CsharpBindings
 
+      - name: Download Wasm definitions
+        uses: actions/download-artifact@v8
+        continue-on-error: true
+        with:
+          name: WasmBindingsDts
+          path: MeshLib/scripts/npm/meshlib
+
       - name: Check for bindings
         id: check_bindings
         run: |

docker/emscriptenDockerfile

@@ -16,7 +16,11 @@ RUN <<EOF
     # install packages
     apt-get update -qqy
     apt-get install -qqy --no-install-recommends \
-        tzdata git pkg-config ninja-build gettext
+        tzdata git pkg-config ninja-build \
+        $(: to compile translation files ) \
+        gettext \
+        $(: to generate TypeScript documentation ) \
+        doxygen
     # clean downloaded files
     apt-get clean
     rm -rf /var/lib/apt/lists/*

doxygen/.gitignore

@@ -2,3 +2,4 @@ DoxygenLayoutMain.xml
 DoxygenLayoutCpp.xml
 DoxygenLayoutPy.xml
 DoxygenLayoutC.xml
+DoxygenLayoutJs.xml

doxygen/APIJsPage.dox

@@ -0,0 +1,7 @@
+/**
+\page APIJsPage JavaScript
+
+ - [Classes](classes.html)
+ - [Files](files.html)
+
+*/

doxygen/layout_templates/base_struct.xml

@@ -79,6 +79,7 @@
       <!-- API_PY_PAGE -->
       <!-- API_C_PAGE -->
       <!-- API_CSHARP_PAGE -->
+      <!-- API_JS_PAGE -->
     </tab>
     <tab type="user" url="__BEGIN_URL__ThirdParty__END_URL__" title="Third-Party Dependencies"/>
   </navindex>

scripts/doxygen/Modules.txt

@@ -1 +1 @@
-Main Cpp Py C Csharp
+Main Cpp Py C Csharp Js

scripts/doxygen/generate_doxygen_layout.sh

@@ -26,6 +26,7 @@ MODULE_PARAMETERS_MATRIX=(
   "PY:Py:Python"
   "C:C:C"
   "CSHARP:Csharp:C#"
+  "JS:Js:JavaScript"
 )
 
 for MODULES_ROW in "${MODULE_PARAMETERS_MATRIX[@]}"; do

scripts/npm/Doxyfile

@@ -0,0 +1,15 @@
+# Doxygen config that extracts the MeshLib C++ API doc comments as XML, for inject_tsdoc.py
+INPUT                = source/MRMesh source/MRVoxels
+RECURSIVE            = YES
+GENERATE_HTML        = NO
+GENERATE_LATEX       = NO
+GENERATE_XML         = YES
+XML_OUTPUT           = build/wasm_cpp_comments
+EXTRACT_ALL          = YES
+ENABLE_PREPROCESSING = YES
+MACRO_EXPANSION      = YES
+EXPAND_ONLY_PREDEF   = YES
+PREDEFINED           = MRMESH_API= MRVOXELS_API= MRIOEXTRAS_API= MRSYMBOLMESH_API= MRVIEWER_API= MR_CANONICAL_TYPEDEFS "MR_BIND_PREFERRED_NAME(x)="
+QUIET                = YES
+WARNINGS             = NO
+WARN_LOGFILE         = /dev/null