Merge branch 'f-fix-jsdoc' into 'dev'

F fix jsdoc

See merge request !148

.gitlab-ci.yml

@@ -93,7 +93,8 @@ pages_prepare: &pages_prepare
     refs:
       - /^release-.*$/i
   script:
-    - npm install jsdoc jsdoc-sphinx
+    - npm install -g jsdoc
+    - npm install @indiscale/jsdoc-sphinx
     - echo "Deploying"
     - make doc
     - rm -r public || true ; cp -r build/doc/html public

CHANGELOG.md

@@ -17,6 +17,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Fixed ###
 
 - [#254](https://gitlab.com/linkahead/linkahead-webui/-/issues/254) "Download files referenced in the table" failed
+- [#230](https://gitlab.com/linkahead/linkahead-webui/-/issues/230)
+  `make doc` is now compatible with npm >= 9.0.0.
 
 ### Security ###
 

README_SETUP.md

@@ -80,13 +80,16 @@ See `build.properties.d/00_default.properties` for more information.
 
 ## Build the documentation #
 
-Build documentation in `build/` with `make doc`.
+Install the below requirements and build documentation in `build/`
+with `make doc`. You may need to set the environment variables used in
+`src/doc/Makefile`, especially `JSDOC_BIN` in case you didn't install
+jsdoc globally.
 
 ### Requirements ##
 
 - sphinx
 - sphinx-autoapi
 - jsdoc (`npm install jsdoc`)
-- jsdoc-sphinx  (`npm install jsdoc-sphinx`)
+- @indiscale/jsdoc-sphinx  (`npm install @indiscale/jsdoc-sphinx`)
 - sphinx-js
 - recommonmark

src/doc/Makefile

@@ -24,16 +24,15 @@
 # It is based upon the autocreated makefile for Sphinx documentation.
 
 # You can set these variables from the command line, and also
-# from the environment for the first two.
+# from the environment for the first four.
 SPHINXOPTS    ?= -a
 SPHINXBUILD   ?= sphinx-build
+NPM_PREFIX ?= ../..
+JSDOC_BIN ?= jsdoc
 # SPHINXAPIDOC  ?= javasphinx-apidoc
 SOURCEDIR      = .
 BUILDDIR       = ../../build/doc
 
-# npm is not always in the global PATH
-NPM_PATH = $(shell npm bin)
-NPM_PREFIX = $(shell npm prefix)
 
 .PHONY: doc-help Makefile api
 
@@ -44,8 +43,8 @@ doc-help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile api
-	PATH=$(NPM_PATH):$$PATH $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 #	sphinx-build -M html . ../../build/doc
 
 api:
-	PATH=$(NPM_PATH):$$PATH jsdoc -t $(NPM_PREFIX)/node_modules/jsdoc-sphinx/template -d $@ -r "../../src/core"
+	$(JSDOC_BIN) -t $(NPM_PREFIX)/node_modules/@indiscale/jsdoc-sphinx/template -d $@ -r "../../src/core"

src/doc/conf.py

@@ -196,7 +196,7 @@ primary_domain = 'js'  # Not strictly necessary?
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {}
 
 # TODO Which options do we want?
 autodoc_default_options = {

src/doc/index.rst

@@ -28,5 +28,4 @@ the most important concepts and offers a range of
 Indices and tables
 ==================
 
-* :ref:`genindex`
 * :ref:`search`