API doc generation improvements

.prettierrc.json

@@ -0,0 +1 @@
+{}

CONTRIBUTING.md

@@ -1,36 +1,101 @@
-## Updating existing documentation for a module
-- This happens in the [Turf repository](https://github.com/turfjs/turf/) with `/packages/` directory for each module. 
-- To fix the documentation for a module you need to modify the [jsdoc](https://jsdoc.app/) for an individual module found in either the `index.js` or the `index.ts`. 
-  - eg to update the documentation for `@turf/along` you'd need to modify the jsdoc within `/turf/packages/turf-along/index.ts`.
-- Once you've made your changes you'll need to create a pull request to the [Turf repository](https://github.com/turfjs/turf/).
-  - **Note** Nothing needs to be changed in the `README.md` for a module.
-- Even once your PR is accepted the docs will still need to be updated manually.
-
-## Updating content on http://turfjs.org/
-1. Clone with `turf-www` repository locally
-  - `git clone https://github.com/Turfjs/turf-www.git --recursive` 
-  - _Important: The `--recursive` flag is important._
-2. Run `npm install`
-3. Start with updating the turf project dependency:
-  - `cd` into the `turf-www/turf` submodule and run `git pull origin master`
-  - Run `lerna run build`, this will update the `dist/js/index.js` for each module, from which the docs are generated.
-4. `cd` back to the root of the `turf-www` project
-5. Run `npm run create-config`
-6. Run `npm run generate`
-7. Commit and push the changes
-
-## Updating pages templates
-If you would like to have a go at updating the actual website then you'll need to make changes in the `turf-www/src` folder. The pages are built using [Vue.js](https://vuejs.org/) and [Nuxt.js](https://nuxtjs.org/).
-
-To get a server running with live-reload etc so you can work on the docs run `npm run start`. 
-
-## Overview for how the docs work
-- http://turfjs.org/ is managed as a static site using Github Pages
-  - A custom domain for Github Pages in present in `/docs/CNAME`
-- The `/src` directory contains the VueJS app
-  - This can be run in a live preview mode using `npm run start`, note that this won't pick up changes to the module documentation.
-- The API docs are generated from jsdoc markup in each module within the `/turf` submodule
-  - [DocumentationJS](https://documentation.js.org/) is used to parse the jsdoc content in each module
-  - The `npm run create-config` cmd calls the `/scripts/create-config.js` file, which generates the `src/assets/config.json` file which is used by the VueJS to render the docs.
-- The `/src` VueJS app, is built into the final deployed docs are built using [NuxtJS](https://nuxtjs.org/) and are found in the `/docs` folder
-  - These are created using the `npm run generate` cmd. 
+## Updating documentation for a module
+
+Documentation is generated automatically wherever possible directly from the Turf source code. Best practice is to submit a PR to update the documentation in the relevant package of the turf repository.
+
+For example, to update the documentation for `@turf/along` you would modify the JSDoc comments within [`/turf/packages/turf-along/index.ts`](https://github.com/Turfjs/turf/blob/master/packages/turf-along/index.ts).
+
+As part of the commit process, the README.md in the turf-along directory will automatically be updated to reflect your changes.
+
+Periodically the Turf website is also updated to reflect the latest documentation generated from the source code. It is similar to the README.md though has some extra features such as interactive example maps.
+
+## Updating the Turf website
+
+The content of the Turf website resides in a separate repository, which links to the turf repo as a submodule.
+
+1. A custom script (generate-api-mdx.ts) generates MDX (extended Markdown) describing the API directly from the Turf source files. generate-api-mdx.ts does any custom handling Turf requires, for example generating the interactive maps used to display examples.
+1. Docusaurus then processes that MDX into a static HTML website.
+1. The HTML files are uploaded to github pages where they become publicly accessible via https://turfjs.org
+
+### Terminology confusion
+
+Docusaurus lets us publish multiple versions of the documentation simultaneously, accessed via a dropdown in the top menu. The terminology used can be a bit confusing though.
+
+Currently on the website we have versions:
+
+| Label | Docusaurus         | Description                                                                                                              |
+| ----- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
+| Next  | Current            | Bleeding edge _unversioned_ documentation from the git repo. Probably hasn't yet been published to NPM                   |
+| 7.0.0 | Latest             | The most recent versioned snapshot of the documentation. This is the default shown to users when first visiting the site |
+| 6.5.0 | a previous version | Archived documentation from a version that is neither Current or Latest                                                  |
+
+When we upload a new release of Turf to NPM we take a snapshot of the _Current_ documentation and copy that into version _whatever_. Docusaurus then points "Latest" at this newly minted version.
+
+### Generate documentation to version as 7.1.0
+
+In this step you will take a snapshot of the _Current_ documentation, and save it as version 7.1.0.
+
+First thing to do is make sure _Current_ points to the code (and hence, the documentation) for 7.1.0. It likely points to the HEAD of the tree, which may not necessarily be 7.1.0, especially if there have already been some bug fixes between releasing to NPM and updating the documentation. So we will temporarily point _Current_ to the 7.1.0 code, generate our 7.1.0 snapshot, and then restore it to what it was.
+
+To do this we link the `turf/` submodule directory in turf-www to the relevant commit in the turf repo. In the example below commit `68915ee` refers to the 7.1.0 tag in the turf repo:
+
+```
+$ git -C turf/ checkout 68915ee
+```
+
+Now that the `turf/` submodule points to 7.1.0 code regenerate the API documentation:
+
+```
+$ npm run generate-api-mdx
+```
+
+You will likely see many changes to MDX files in the `docs/` directory.
+
+Run docusaurus to view the site in dev mode and highlight any missing routes, etc. Docusaurus is pretty good at finding problems. Fix any issues manually, usually by tweaking the MDX.
+
+```
+$ npm run build
+$ npm run serve
+```
+
+Note the generated documentation will appear under the _Next_ drop down menu.
+
+You could at this point commit the changes. However we're about to make a versioned snapshot which we _will_ commit, so it's not absolutely necessary.
+
+Now, version the contents of _Current_ as 7.1.0:
+
+```
+$ npm run docusaurus docs:version 7.1.0
+```
+
+You will now see many more changes in the `versioned_docs` directory. This is the snapshot we want to commit and publish. Before we do that though, switch back to the HEAD of our git repo and regenerate the _Current_ documentation based on that code:
+
+```
+$ git submodule update --init
+$ npm run generate-api-mdx
+```
+
+Most, if not all, of the changes in docs/ should revert. If any remain review them as they may have previously been committed as manual corrections (and thus can be discarded).
+
+You'll likely have changes in these locations:
+
+```
+api-sidebar.ts <- might change
+versions.json <- should be a line added for the new version snapshot
+docs/ <- maybe a couple of changed files
+versioned_docs/ <- many new files
+versioned_sidebars/ <- one new file
+```
+
+Once everything looks good, commit all the files and push to your fork:
+
+```
+$ git add .
+$ git commit -m "Adding v7.1.0 documentation snapshot."
+$ git push
+```
+
+### Publishing to turfjs.org
+
+To build and publish the site, you simply need to create a PR from your fork to turf-www:master. This will run a test build as a github action.
+
+When your PR is merged into master, another github action will deploy the content automatically to github pages.

api-sidebar.ts

@@ -220,6 +220,7 @@ export default [
       "api/booleanCrosses",
       "api/booleanDisjoint",
       "api/booleanEqual",
+      "api/booleanIntersects",
       "api/booleanOverlap",
       "api/booleanParallel",
       "api/booleanPointInPolygon",
@@ -233,6 +234,7 @@ export default [
     label: "Unit Conversion",
     collapsed: false,
     items: [
+      "api/azimuthToBearing",
       "api/bearingToAzimuth",
       "api/convertArea",
       "api/convertLength",
@@ -251,7 +253,6 @@ export default [
     collapsed: false,
     items: [
       "api/angle",
-      "api/booleanIntersects",
       "api/booleanValid",
       "api/centerMean",
       "api/centerMedian",
@@ -266,17 +267,63 @@ export default [
       "api/lineEach",
       "api/lineReduce",
       "api/lineStrings",
-      "api/mean",
       "api/moranIndex",
+      "api/nearestNeighborAnalysis",
       "api/nearestPointToLine",
       "api/pNormDistance",
       "api/points",
       "api/polygons",
-      "api/pt",
       "api/quadratAnalysis",
       "api/rbush",
+      "api/rectangleGrid",
       "api/standardDeviationalEllipse",
-      "api/variance",
+    ],
+  },
+  {
+    type: "category",
+    label: "Type Definitions",
+    collapsed: false,
+    items: [
+      "api/types/AllGeoJSON",
+      "api/types/AreaUnits",
+      "api/types/Corners",
+      "api/types/Dbscan",
+      "api/types/DbscanProps",
+      "api/types/DirectionalMeanLine",
+      "api/types/Grid",
+      "api/types/Lines",
+      "api/types/MoranIndex",
+      "api/types/NearestNeighborStatistics",
+      "api/types/NearestNeighborStudyArea",
+      "api/types/QuadratAnalysisResult",
+      "api/types/Units",
+      "api/types/clusterEachCallback",
+      "api/types/clusterReduceCallback",
+      "api/types/coordEachCallback",
+      "api/types/coordReduceCallback",
+      "api/types/featureEachCallback",
+      "api/types/featureReduceCallback",
+      "api/types/flattenEachCallback",
+      "api/types/flattenReduceCallback",
+      "api/types/geomEachCallback",
+      "api/types/geomReduceCallback",
+      "api/types/lineEachCallback",
+      "api/types/lineReduceCallback",
+      "api/types/propEachCallback",
+      "api/types/propReduceCallback",
+      "api/types/segmentEachCallback",
+      "api/types/segmentReduceCallback",
+    ],
+  },
+  {
+    type: "category",
+    label: "Constants",
+    collapsed: false,
+    items: [
+      "api/constants/K_TABLE",
+      "api/constants/areaFactors",
+      "api/constants/earthRadius",
+      "api/constants/factors",
     ],
   },
 ];

docs/api/along.mdx

@@ -4,27 +4,29 @@ title: along
 
 import * as turf from "turf-next";
 import ExampleMap from "@site/src/components/ExampleMap";
+import WindowTurfGlobal from "@site/src/components/WindowTurfGlobal";
 import BrowserOnly from "@docusaurus/BrowserOnly";
 
+<!-- Expose turf as global var for experimenting in the browser console -->
+
+<BrowserOnly>{() => <WindowTurfGlobal turf={turf} />}</BrowserOnly>
+
 ### Description
 
 Takes a [LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4) and returns a [Point](https://tools.ietf.org/html/rfc7946#section-3.1.2) at a specified distance along the line.
 
 ### Parameters
 
-| Name                  | Type                                                                                                                              | Description                                                            |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
-| line                  | **[Feature](https://tools.ietf.org/html/rfc7946#section-3.2)\<[LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4)\>** | input line                                                             |
-| distance              | **number**                                                                                                                        | distance along the line                                                |
-| options<i>?</i>       | **Object**                                                                                                                        | Optional parameters                                                    |
-| options.units<i>?</i> | **string**                                                                                                                        | can be degrees, radians, miles, or kilometers _(default "kilometers")_ |
+| Name                  | Type                                                                                                                                                                                                 | Description                                                            |
+| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
+| line                  | **[Feature](https://tools.ietf.org/html/rfc7946#section-3.2)\<[LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4)\> \| [LineString](https://tools.ietf.org/html/rfc7946#section-3.1.4)** | input line                                                             |
+| distance              | **[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)**                                                                                                      | distance along the line                                                |
+| options<i>?</i>       | **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**                                                                                                      | Optional parameters _(default \{\})_                                   |
+| options.units<i>?</i> | **[Units](docs/api/types/Units.mdx)**                                                                                                                                                                | can be degrees, radians, miles, or kilometers _(default "kilometers")_ |
 
 ### Returns
 
-<ul>
-  **[Feature](https://tools.ietf.org/html/rfc7946#section-3.2)\<[Point](https://tools.ietf.org/html/rfc7946#section-3.1.2)\>** Point `distance` `units` along the line
-
-</ul>
+**[Feature](https://tools.ietf.org/html/rfc7946#section-3.2)\<[Point](https://tools.ietf.org/html/rfc7946#section-3.1.2)\>** Point `distance` `units` along the line
 
 ### Examples
 
@@ -59,7 +61,6 @@ export function Map0() {
   return <ExampleMap addToMap={addToMap} />;
 }
 
-<!-- prettier-ignore -->
 <BrowserOnly>{() => <Map0 />}</BrowserOnly>
 
 ### Installation

docs/api/angle.mdx

@@ -4,30 +4,32 @@ title: angle
 
 import * as turf from "turf-next";
 import ExampleMap from "@site/src/components/ExampleMap";
+import WindowTurfGlobal from "@site/src/components/WindowTurfGlobal";
 import BrowserOnly from "@docusaurus/BrowserOnly";
 
+<!-- Expose turf as global var for experimenting in the browser console -->
+
+<BrowserOnly>{() => <WindowTurfGlobal turf={turf} />}</BrowserOnly>
+
 ### Description
 
 Finds the angle formed by two adjacent segments defined by 3 points. The result will be the (positive clockwise)
 angle with origin on the `startPoint-midPoint` segment, or its explementary angle if required.
 
 ### Parameters
 
-| Name                         | Type                                                           | Description                                                                             |
-| ---------------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
-| startPoint                   | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)** | Start Point Coordinates                                                                 |
-| midPoint                     | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)** | Mid Point Coordinates                                                                   |
-| endPoint                     | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)** | End Point Coordinates                                                                   |
-| options<i>?</i>              | **Object**                                                     | Optional parameters _(default \{\})_                                                    |
-| options.explementary<i>?</i> | **boolean**                                                    | Returns the explementary angle instead (360 - angle) _(default false)_                  |
-| options.mercator<i>?</i>     | **boolean**                                                    | if calculations should be performed over Mercator or WGS84 projection _(default false)_ |
+| Name                         | Type                                                                                              | Description                                                                             |
+| ---------------------------- | ------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
+| startPoint                   | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)**                                    | Start Point Coordinates                                                                 |
+| midPoint                     | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)**                                    | Mid Point Coordinates                                                                   |
+| endPoint                     | **[Coord](https://tools.ietf.org/html/rfc7946#section-3.1.1)**                                    | End Point Coordinates                                                                   |
+| options<i>?</i>              | **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)**   | Optional parameters _(default \{\})_                                                    |
+| options.explementary<i>?</i> | **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** | Returns the explementary angle instead (360 - angle) _(default false)_                  |
+| options.mercator<i>?</i>     | **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** | if calculations should be performed over Mercator or WGS84 projection _(default false)_ |
 
 ### Returns
 
-<ul>
-  **number** Angle between the provided points, or its explementary.
-
-</ul>
+**[number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)** Angle between the provided points, or its explementary.
 
 ### Examples