Merge pull request #79 from python-project-templates/tkp/b

Add sphinx-js integration

Author: timkpaine

.github/workflows/build.yaml

@@ -42,6 +42,14 @@ jobs:
     - name: Install Rust
       uses: dtolnay/rust-toolchain@stable
 
+    - name: Setup Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: '20'
+
+    - name: Install JSDoc/TypeDoc
+      run: npm install -g jsdoc typedoc
+
     - name: Install doxygen
       run: sudo apt-get install -y doxygen
 

.github/workflows/docs.yaml

@@ -15,6 +15,14 @@ jobs:
       - name: Install Rust
         uses: dtolnay/rust-toolchain@stable
 
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install JSDoc/TypeDoc
+        run: npm install -g jsdoc typedoc
+
       - name: Install doxygen
         run: sudo apt-get install -y doxygen
 

docs/src/api.md

@@ -103,3 +103,47 @@ Or document specific structs, enums, and functions:
 
 ```
 
+## JavaScript Example
+
+This is an example of documenting JavaScript code using sphinx-js integration.
+
+### Document Functions
+
+Use `js:autofunction` to document individual functions:
+
+```{eval-rst}
+.. js:autofunction:: add
+
+```
+
+```{eval-rst}
+.. js:autofunction:: subtract
+
+```
+
+```{eval-rst}
+.. js:autofunction:: multiply
+
+```
+
+```{eval-rst}
+.. js:autofunction:: divide
+
+```
+
+### Document Classes
+
+Use `js:autoclass` to document classes:
+
+```{eval-rst}
+.. js:autoclass:: Calculator
+   :members:
+
+```
+
+```{eval-rst}
+.. js:autoclass:: ScientificCalculator
+   :members:
+
+```
+

docs/src/configuration.md

@@ -562,3 +562,118 @@ Then in your documentation files, you can use sphinx-rust directives:
 
 \`\`\`
 ````
+
+## Sphinx-JS Integration
+
+Yardang provides integration with [sphinx-js](https://pypi.org/project/sphinx-js/) for documenting JavaScript and TypeScript code. To use this feature, you also need JSDoc or TypeDoc installed:
+
+```bash
+# For JavaScript projects
+npm install jsdoc
+
+# For TypeScript projects
+npm install typedoc
+```
+
+All sphinx-js configuration is under `[tool.yardang.sphinx-js]`.
+
+### `js-source-path`
+
+A list of directories containing your JS/TS source files, relative to the project root. This is required to enable sphinx-js.
+
+```toml
+[tool.yardang.sphinx-js]
+js-source-path = ["src", "lib"]
+```
+
+Or as a single path:
+
+```toml
+[tool.yardang.sphinx-js]
+js-source-path = "src"
+```
+
+### `js-language`
+
+The language of your source files. Use `"javascript"` (default) or `"typescript"`.
+
+```toml
+[tool.yardang.sphinx-js]
+js-language = "typescript"
+```
+
+### `root-for-relative-js-paths`
+
+The root directory for resolving relative JS entity paths. Required if you have multiple `js-source-path` entries.
+
+```toml
+[tool.yardang.sphinx-js]
+root-for-relative-js-paths = "src"
+```
+
+### `jsdoc-config-path`
+
+Path to a JSDoc configuration file.
+
+```toml
+[tool.yardang.sphinx-js]
+jsdoc-config-path = "jsdoc.json"
+```
+
+### `jsdoc-tsconfig-path`
+
+Path to a TypeScript configuration file (for TypeDoc).
+
+```toml
+[tool.yardang.sphinx-js]
+jsdoc-tsconfig-path = "tsconfig.json"
+```
+
+### `ts-type-bold`
+
+Make TypeScript types bold in the output. Defaults to `false`.
+
+```toml
+[tool.yardang.sphinx-js]
+ts-type-bold = true
+```
+
+### Complete Example
+
+Here's a complete example configuration for a TypeScript project:
+
+```toml
+[tool.yardang]
+title = "My TypeScript Library"
+root = "docs/index.md"
+pages = ["docs/api.md", "docs/examples.md"]
+use-autoapi = false
+
+[tool.yardang.sphinx-js]
+js-language = "typescript"
+js-source-path = ["src"]
+jsdoc-tsconfig-path = "tsconfig.json"
+ts-type-bold = true
+```
+
+Then in your documentation files, you can use sphinx-js directives:
+
+````markdown
+# API Reference
+
+## Functions
+
+\`\`\`{js:autofunction} myFunction
+\`\`\`
+
+## Classes
+
+\`\`\`{js:autoclass} MyClass
+:members:
+\`\`\`
+
+## Modules
+
+\`\`\`{js:automodule} myModule
+\`\`\`
+````

examples/js/.gitignore

@@ -0,0 +1,2 @@
+node_modules/
+docs/

examples/js/README.md

@@ -0,0 +1,32 @@
+# JavaScript Calculator Example
+
+This is an example JavaScript project demonstrating sphinx-js documentation with yardang.
+
+## Features
+
+- Basic arithmetic operations (add, subtract, multiply, divide)
+- Calculator class with operation history
+- Scientific calculator with trigonometric functions
+- Full JSDoc documentation
+
+## Usage
+
+```javascript
+import { Calculator, Operation, add, multiply } from 'calculator';
+
+// Using standalone functions
+const sum = add(5, 3);  // 8
+const product = multiply(4, 5);  // 20
+
+// Using the Calculator class
+const calc = new Calculator();
+calc.calculate(10, 5, Operation.ADD);  // 15
+calc.calculate(20, 4, Operation.DIVIDE);  // 5
+
+// View history
+console.log(calc.getHistory());
+```
+
+## Documentation
+
+Documentation is generated using JSDoc and integrated into the main yardang documentation using sphinx-js.

examples/js/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "calculator",
+  "version": "1.0.0",
+  "description": "A simple calculator library demonstrating JavaScript documentation with sphinx-js",
+  "main": "src/index.js",
+  "type": "module",
+  "scripts": {
+    "docs": "jsdoc src -d docs"
+  },
+  "keywords": ["calculator", "math", "example"],
+  "author": "yardang authors",
+  "license": "Apache-2.0",
+  "devDependencies": {
+    "jsdoc": "^4.0.0"
+  }
+}