docs(all): V3 documentation changes

Author: z3dev

jsdoc.json

@@ -3,6 +3,7 @@
     "include": [
       "packages/array-utils/src",
 
+      "packages/modeling/src",
       "packages/modeling/src/colors",
       "packages/modeling/src/curves",
       "packages/modeling/src/curves/bezier",
@@ -35,15 +36,22 @@
       "packages/modeling/src/text",
       "packages/modeling/src/utils",
 
+      "packages/io/io/src",
       "packages/io/io-utils",
-      "packages/io/amf-deserializer/src",
-      "packages/io/amf-serializer",
+      "packages/io/3mf-deserializer/src",
+      "packages/io/3mf-serializer/src",
+      "packages/io/dxf-deserializer/src",
+      "packages/io/dxf-serializer/src",
+      "packages/io/json-deserializer/src",
+      "packages/io/json-serializer/src",
+      "packages/io/obj-deserializer/src",
+      "packages/io/obj-serializer/src",
+      "packages/io/stl-deserializer/src",
+      "packages/io/stl-serializer/src",
       "packages/io/svg-deserializer/src",
-      "packages/io/svg-serializer",
+      "packages/io/svg-serializer/src",
       "packages/io/x3d-deserializer/src",
-      "packages/io/x3d-serializer/src",
-      "packages/io/3mf-deserializer/src",
-      "packages/io/3mf-serializer/src"
+      "packages/io/x3d-serializer/src"
     ],
     "includePattern": ".+\\.js(doc|x)?$",
     "excludePattern": ".+test.js$"
@@ -54,7 +62,7 @@
     "tutorials": "./jsdoc/tutorials",
     "readme": "./jsdoc/assets/README.md"
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": ["jsdoc/jsdocFix","plugins/markdown"],
   "templates": {
     "default": {
       "staticFiles": {
@@ -86,8 +94,8 @@
       "url": ""
     },
     "meta": {
-      "title": "JSCAD API Documentation",
-      "description": "JSCAD API Documentation",
+      "title": "JSCAD V3 API Documentation",
+      "description": "JSCAD V3 API Documentation",
       "keyword": "JSCAD OpenJSCAD"
     },
     "search": [true],

jsdoc/assets/README.md

@@ -23,8 +23,8 @@ There are different 'flavors' of JSCAD that you can use based on your needs
 
 ## Documentation
 
-* [JSCAD User Guide](https://openjscad.xyz/guide.html)
-* [API Reference](https://openjscad.xyz/docs/)
+* [JSCAD User Guide](https://openjscad.xyz/v3/guide.html)
+* [API Reference](https://openjscad.xyz/v3/docs/)
 * [Open Issues](https://openjscad.xyz/issues.html)
 
 ## Community

jsdoc/assets/static/jscad-docs.css

@@ -5,6 +5,7 @@ body {
 
 nav {
     background: none;
+    padding-bottom: 10px;
 }
 
 section {

jsdoc/jsdocFix.js

@@ -0,0 +1,9 @@
+const newDocletFix = (docHandle) => {
+  if (docHandle.doclet.params) {
+    docHandle.doclet.kind = "function"
+  }
+}
+
+exports.handlers = {
+  newDoclet: newDocletFix
+}

jsdoc/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "package to fix jsdoc"
+}

jsdoc/tutorials/01_gettingStarted.md

@@ -23,34 +23,17 @@ it with the "Load a JSCAD Project" file dialog.
 The simplest file that will render a cube in JSCAD looks like this:
 ```javascript
 // the import statement allows your code to use JSCAD functions.
-import { primitives } from '@jscad/modeling'
+import { cube } from '@jscad/modeling'
 
 // the export statement defines the entry point of the design.
 export const main = () => {
-  return primitives.cube()
+  return cube()
 }
 ```
-JSCAD functions must be imported, but there are several different syntaxes for using the functions:
-```javascript
-// import one or more functional areas from JSCAD:
-import { primitives, booleans } from '@jscad/modeling'
-
-// use functions directly
-let aCube = primitives.cube()
-
-// or
-
-// use the functions by name
-const { cube, sphere } = primitives
-
-let aCube = cube()
-let aSphere = sphere()
-```
 ## Adding Methods
 Clean, readable code is one of the most important aspects of a useful design. In that respect, it can often be useful to break your code into simple function that do part of the work for your design:
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 const hex = (radius, height) => {
     return cylinder({radius, height, segments: 6})
@@ -63,8 +46,7 @@ export const main = () => {
 ## Re-usable Designs
 A valuable practise when creating models is to store all but the most trivial values as parameters in the code, rather than using the numerical values directly.  This can be done by storing them in constants in your file...
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 const options = {
     height: 5.1,
@@ -78,10 +60,10 @@ export const main = () => {
 
 ... or, even better, to include runtime parameters in your design.  This is done using the getParameterDefinitions function:
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 // Declare a function named "getParameterDefinitions". It will return an array of parameter definitions.
+// You must also export the getParameterDefinitions function.
 export const getParameterDefinitions = () => {
   return [
     { name: 'height', type: 'number', initial: 2.0, min: 1.0, max: 10.0, step: 0.1, caption: 'Hex Height:' },
@@ -93,7 +75,6 @@ export const getParameterDefinitions = () => {
 export const main = (params) => {
   return cylinder({radius: params.radius, height: params.height, segments: 6})
 }
-// You must also export the getParameterDefinitions function.
 ```
 <img src="img/parameters.png" alt="JSCAD Parameters Example">
 

jsdoc/tutorials/02_modelingBasics.md

@@ -38,9 +38,7 @@ Another valuable way of building shapes is to start with 2D shapes.  These can b
 specifying points, starting with basic primitive 2D shapes, or importing SVG files.  The 2D 
 shapes can then be extruded to produce a wide variety of different geometries.
 ```javascript
-import { primitives, extrusions } from '@jscad/modeling'
-const { polygon } = primitives
-const { extrudeLinear } = extrusions
+import { polygon, extrudeLinear } from '@jscad/modeling'
 
 export const main = () => {
     const poly = polygon({ points: [[-1, -1], [3, -1], [3.5, 2], [2, 1], [1, 2], [0, 1], [-1, 2]] })

jsdoc/tutorials/03_usingParameters.md

@@ -3,9 +3,7 @@ your designs, so that they can easily adapt to different situations.
 
 ## ParametricBox.js
 ```javascript
-import { primitives, booleans } from  '@jscad/modeling'
-const { cuboid, roundedCuboid } = primitives
-const { subtract } = booleans
+import { cuboid, roundedCuboid, subtract } from  '@jscad/modeling'
 
 export const getParameterDefinitions = () => {
   return [

jsdoc/tutorials/04_multifileProjects.md

@@ -21,14 +21,13 @@ contain your design. Your project can also contain:
 ```
 ## hexcap/index.js
 ```javascript
-import { primtives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 import { hexWidthToRadius }  from './lib/utils.js'
 
 export const main = () => {
-  let hexRadius = utils.hexWidthToRadius(12)
-  return cylinder({radius: hexRadius, height: 4, segments: 6})
+  let radius = hexWidthToRadius(12)
+  return cylinder({radius, height: 4, segments: 6})
 }
 ```
 ## hexcap/lib/utils.js

jsdoc/tutorials/05_importingFiles.md

@@ -1,10 +1,11 @@
 Importing files in JSCAD is a simple case of loading them using the same import statement used to load javascript modules.  The files you load need to be part of a multifile project, so that JSCAD can access them:
 
 ```javascript
+// import all functions and global constants
 import * as jscad from '@jscad/modeling'
 
-const { translate, scale, rotateZ } = jscad.transforms
-const { union } = jscad.booleans
+// import specific functions and global constants by name
+const { translate, scale, rotateZ, union, TAU } = '@jscad/modeling'
 
 // Load the STL files using require
 const sculpture = require('./3d_sculpture-VernonBussler.stl')