update jsdoc template to docdash

cds-astro · Sep 24, 2024 · f79d47d · f79d47d
1 parent e6321f3
commit f79d47d
Show file tree

Hide file tree

Showing 6 changed files with 76 additions and 18 deletions.
diff --git a/jsdoc-custom-style.css b/jsdoc-custom-style.css
@@ -0,0 +1,8 @@
+nav > h2 {
+    color: blue;
+    font-size: medium;
+}
+
+nav > ul > li > a {
+    font-size: medium;
+}
diff --git a/jsdoc.json b/jsdoc.json
@@ -10,13 +10,64 @@
         "allowUnknownTags": true,
         "dictionaries": ["jsdoc","closure"]
     },
+    "docdash": {
+        "scripts": [
+            "jsdoc-custom-style.css"
+        ],
+        "sectionOrder": [
+            "Namespaces",
+            "Classes",
+            "Modules",
+            "Externals",
+            "Events",
+            "Mixins",
+            "Tutorials",
+            "Interfaces"
+       ],
+       "openGraph": {
+            "title": "Aladin Lite API documentation",
+            "type": "website",
+            "image": "https://cds-astro.github.io/aladin-lite/aladin-logo.png",
+            "site_name": "Aladin Lite API documentation",
+            "url": "https://cds-astro.github.io/aladin-lite/"
+        },
+        "meta": {
+            "title": "Aladin Lite API documentation",
+            "description": "Aladin Lite API documentation",
+            "keyword": "astronomy"
+        },
+       "search": true,
+       "menu": {                      
+            "Project Website": {        
+                "href":"https://aladin.cds.unistra.fr/AladinLite/doc/",
+                "target":"_blank",
+                "class":"menu-item",
+                "id":"website_link"
+            },
+            "Forum": {
+                "href":"https://github.com/cds-astro/aladin-lite/issues",
+                "target":"_blank",
+                "class":"menu-item",
+                "id":"forum_link"
+            }
+        }
+    },
     "templates": {
         "cleverLinks": true,
-        "monospaceLinks": true
+        "monospaceLinks": true,
+        "default": {
+            "staticFiles": {
+                "include": [
+                  "./jsdoc-custom-style.css"
+                ]
+            }
+        }
     },
     "opts": {
         "readme": "./README.md",
         "destination": "./docs/",
-        "tutorials": "./tutorials"
+        "template": "node_modules/docdash",
+        "encoding": "utf8",
+        "verbose": true
     }
-}
+}
diff --git a/package.json b/package.json
@@ -44,11 +44,12 @@
     "test:build": "cd src/core && cargo test --release --features webgl2",
     "test:playwright": "npx playwright test",
     "test:update-snapshots": "npx playwright test --update-snapshots",
-    "doc": "jsdoc -c jsdoc.json src/js src/js/shapes src/js/libs/astro && cp aladin-logo.png docs/",
+    "doc": "jsdoc -c jsdoc.json src/js src/js/shapes src/js/libs/astro && cp aladin-logo.png docs/ && cp jsdoc-custom-style.css docs/",
     "doc:dev": "npm run doc && open docs/index.html"
   },
   "devDependencies": {
     "@playwright/test": "^1.47.0",
+    "docdash": "^2.0.2",
     "jsdoc": "^4.0.2",
     "vite": "^4.3.8",
     "vite-plugin-glsl": "^1.1.2",

diff --git a/src/js/AladinUtils.js b/src/js/AladinUtils.js
@@ -182,20 +182,21 @@ export let AladinUtils = {
          * @param {number} ra - Right Ascension (RA) coordinate in degrees.
          * @param {number} dec - Declination (Dec) coordinate in degrees.
          * @param {Aladin} aladin - Aladin Lite object containing the WebAssembly API.
-         * @returns {number[]} xy - A 2 elements array representing the screen coordinates [X, Y] in pixels.
+         * @returns {number[]} A 2 elements array representing the screen coordinates [X, Y] in pixels.
          */
         radecToViewXy: function(ra, dec, aladin) {
             return aladin.world2pix(ra, dec);
         },
 
         /**
+         * Convert a number in degrees into a string<br>
+         * 
         * @function
         * @memberof AladinUtils
         * @name degreesToString
-        * Convert a number in degrees into a string<br>
-        *
+        * 
         * @param numberDegrees number in degrees (integer or decimal)
-        * @return a formattes string
+        * @return the formatted string
         * 
         * @example <caption> Result in degrees </caption>
         * // returns "1°"

diff --git a/src/js/HiPS.js b/src/js/HiPS.js
@@ -128,8 +128,8 @@ PropertyParser.isPlanetaryBody = function (properties) {
 };
 
 /**
+ * HiPS options
  * @typedef {Object} HiPSOptions
- *
  * @property {string} [name] - The name of the survey to be displayed in the UI
  * @property {Function} [successCallback] - A callback executed when the HiPS has been loaded
  * @property {Function} [errorCallback] - A callback executed when the HiPS could not be loaded
@@ -155,19 +155,16 @@ PropertyParser.isPlanetaryBody = function (properties) {
  */
 
 /**
- * @typedef {Object} FileList
- * 
  * JS {@link https://developer.mozilla.org/fr/docs/Web/API/FileList| FileList} API type
+ * 
+ * @typedef {Object} FileList
  */
 
 /**
- * @typedef {Object} HiPSLocalFiles
- * 
- * @property {File} properties - The local properties file of the HiPS
- * 
- * @description
  * Tiles are accessed like so: HIPSLocalFiles[norder][ipix] = {@link File};<br/>
  * The properties file is accessed with: HIPSLocalFiles["properties"]
+ * @typedef {Object} HiPSLocalFiles
+ * @property {File} properties - The local properties file of the HiPS
  */
 
 

diff --git a/src/js/MOC.js b/src/js/MOC.js
@@ -222,8 +222,8 @@ export let MOC = (function() {
      /**
      * Serialize a MOC into different format
      *
-     * @memberof Aladin
-     * @param {string} [format='json'] - The output format. Only json is currently supported but 'fits' could be added.
+     * @memberof MOC
+     * @param {string} [format='json'] - The output format. Only `json` is currently supported but `fits` could be added.
      */
     MOC.prototype.serialize = function(format) {
         if (!this.ready) {