F fix jsdoc

Summary

Fixes https://gitlab.indiscale.com/caosdb/customers/f-fit/management/-/issues/116 (https://gitlab.com/linkahead/linkahead-webui/-/issues/230). Use our fork of jsdoc-sphinx and update documentation setup to work with modern systems.

Focus

Mainly uses the now compatible https://www.npmjs.com/package/@indiscale/jsdoc-sphinx. The rest are just fixes for changes that happened in npm and sphinx since we started this documentation.

Test Environment

Follow the documentation section of README_SETUP.md and verify that the documentation builds correctly. Especially, there has to be an API section in the table of contents.

You can also verify the pipeline fix in https://gitlab.indiscale.com/caosdb/src/caosdb-webui/-/pipelines/59138 where I enabled the page building also for this f-branch.

Check List for the Author

Please, prepare your MR for a review. Be sure to write a summary and a focus and create gitlab comments for the reviewer. They should guide the reviewer through the changes, explain your changes and also point out open questions. For further good practices have a look at our review guidelines

• All automated tests pass
• Reference related issues
• Up-to-date CHANGELOG.md (or not necessary)
• Up-to-date JSON schema (or not necessary)
• Appropriate user and developer documentation (or not necessary)
  • How do I use the software? Assume "stupid" users.
  • How do I develop or debug the software? Assume novice developers.
• Annotations in code (Gitlab comments)
  • Intent of new code
  • Problems with old code
  • Why this implementation?

Check List for the Reviewer

• I understand the intent of this MR
• All automated tests pass
• Up-to-date CHANGELOG.md (or not necessary)
• Appropriate user and developer documentation (or not necessary)
• The test environment setup works and the intended behavior is reproducible in the test environment
• In-code documentation and comments are up-to-date.
• Check: Are there specifications? Are they satisfied?

For further good practices have a look at our review guidelines.

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"