Mobx docs #4666

rowanwins · 2020-08-25T05:10:01Z

What this PR does

Fixes #4502

This PR does various docs things for the next branch.

Automate the table-of-contents in mkdocs.yml
Automate the lists on the catalog-items.md and catalog-groups.md pages
Automate the table-of-contents in mkdocs.yml
Generate docs from model traits, as well as allowing some jsdoc comments to be retrieved for general description and examples

Learnings

I'm using documentation.js as it has a node API for retrieving jsdoc style stuff from files.
- however the json it returns can be pretty fiddily to work with
I ran into issues with reading jsdoc from lib/Models so ended up throwing things in lib/Traits which seems to kinda be working
I went for a table-based layout for scan-ability given the large number of traits most models have.

Things to do

Harden up process for with documentationjs for examples and general description.
Add more examples and general descriptions for other models.
- At the moment I've done Cesium 3D Tiles and WMS just as samples
Better understand and update the release process. basically npm run publish-doc needs updating I think...

Checklist

No unit tests required
I've updated CHANGES.md with what I changed.

tephenavies · 2020-09-14T08:35:37Z

My only hesitation with this PR is that it mixes Traits with JSDoc. Maybe we should put examples in code somewhere? As JSON. We could then include them in tests (having all of our examples automatically tested would be cool) or in the catalog editor.

README.md are now turned into index.html by mkdocs (in the absence of an index.md)

soyarsauce · 2020-09-23T05:04:30Z

@steve9164 @rowanwins Yes avoiding the examples in jsdoc would be good, I wouldn't want it to stop things though. Having the examples as JSON is better for sure to allow for including them in tests among other things.

Re: catalog editor, the JSON example would be less useful given you aren't typically editing it via JSON, but could be useful for it yes.

# Conflicts: # .gitignore # lib/ModelMixins/Cesium3dTilesMixin.ts # lib/Traits/WebMapServiceCatalogItemTraits.ts

soyarsauce · 2020-09-23T05:15:02Z

Also minor regression due to putting HTML in traits (it's treated as markdown in the editor)

Previous (`next`)

`mobx-docs`

…ate property

tephenavies · 2020-09-23T07:56:13Z

Hmmm, after re-discovering these JSDoc-derived docs https://docs.terria.io/reference/ I no longer mind adding JSDoc back into the build process as it'd be good to have these reference docs once we have more things JSDoc'd and as Wing pointed out the catalog editor has no real use for example JSON.

I think it's alright as is, apart from the <br/> changes, which we should revert if possible .

doc/connecting-to-data/catalog-groups.md

.gitignore

buildprocess/webpack-docs.config.js

doc/connecting-to-data/catalog-type-details/3d-tiles.md

gulpfile.js

tephenavies · 2020-09-24T08:20:16Z

package.json

@@ -194,6 +195,8 @@
    "start": "terriajs-server --port 3002",
    "dev": "webpack-dev-server --inline --config buildprocess/webpack.config.dev.js --host 0.0.0.0",
    "hot": "webpack-dev-server --inline --config buildprocess/webpack.config.hot.js --hot --host 0.0.0.0",
+    "build-docs": "webpack --config buildprocess/webpack-docs.config.js && node modeldocs/generateDocs.js",


This should probably be part of a gulp task that gets called by gulp docs. I think there's a bit too much complexity to the whole doc generation thing to have it all in npm scripts

doc/connecting-to-data/catalog-type-details/3d-tiles.md

tephenavies · 2020-09-25T01:58:26Z

doc/connecting-to-data/catalog-type-details/undefined.md

+
+## Properties
+
+"type": "undefined"


Looks like this type has been ascertained incorrectly

Seems to be something to do with WPS but haven't quite worked out what yet....

tephenavies · 2020-09-25T02:06:04Z

mkdocs.yml

@@ -0,0 +1,81 @@
+site_name: TerriaJS


I'd prefer to keep this file in doc/. What's the reason to pull it out to the root?

I'm not sure if this is due to a version change in mkdocs or something

If I keep doc/mkdocs.yml and set it to

.... docs_dir: / site_dir: ./../wwwroot/doc/guide ...

If I try and run mkdocs build I get something like

ERROR - Config value: 'site_dir'. Error: The 'site_dir' should not be within the 'docs_dir' as this leads to the build directory being copied into itself and duplicate nested files in the 'site_dir'.(site_dir: '/Users/win167/Documents/Code/TerriaMapMobx/packages/terriajs/wwwroot/doc/guide', docs_dir: '/')

Short answer is I can't make it work 🤷‍♂️

Ahh ok. Actually I should probably merge my mkdocs update on master into this PR before we continue. I think it solves that issue.

Fix CI PR build for external contributors

tephenavies · 2020-10-02T02:51:47Z

@rowanwins Any chance you can advance this?

…butions Update Basemaps url and attributions

https://app.netlify.com/sites/terriajs-docs-v8/deploys

tephenavies · 2020-11-27T08:47:28Z

Switched all build outputs to be in build. If any markdown file is generated, it's output is written into build/doc, after /doc markdown files are copied there.

zoran995 · 2020-12-07T09:01:57Z

Should we document the usage of search providers (i.e. proper config to set them in TerriaMap), I am working on Esri geocoder support

zoran995 · 2020-12-07T09:11:58Z

Also, can we add the required next to the required parameters in doc?
RasterLayerTraits.ts#L69-L73 is split into multiple rows in docs

Changes made

tephenavies · 2021-01-14T04:45:06Z

Ignore the license/cla check. The author of that code accepted the CLA when the PR was merged, but must have changed their GitHub settings since so the commits are not associated. We still have the name in our CLA register though, and their contribution still falls under the CLA they signed.

doc/customizing/skinning.md

requirements.txt

lib/Traits/DiscretelyTimeVaryingTraits.ts

lib/Traits/TimeVaryingTraits.ts

buildprocess/webpack-docs.config.js

draugnim · 2021-01-18T14:00:05Z

I was not able to build the docs with 'npm run build-docs '. The error was:

Error: ENOENT: no such file or directory, open 'doc/connecting-to-data/catalog-type-details/esri-group.md' at Object.openSync (fs.js:457:3) at Object.writeFileSync (fs.js:1282:35) at processArray (webpack:///./buildprocess/generateDocs.js?:211:47) at async generateDocs (webpack:///./buildprocess/generateDocs.js?:269:7) { errno: -4058, syscall: 'open', code: 'ENOENT', path: 'doc/connecting-to-data/catalog-type-details/esri-group.md' }

I manually created the 'doc/connecting-to-data/catalog-type-details' folder and the build passed.

tephenavies · 2021-01-19T02:13:58Z

Hi @draugnim. Thanks for letting me know. npm run build-docs is an old script for building docs (introduced in this PR but replaced by gulp docs/npm run gulp docs). I'll remove it to avoid confusion.

draugnim · 2021-01-19T12:54:46Z

I first tried with that function but it failed with

YDYRCatalogFunctionJob ydyr-job
YDYRCatalogFunctionJob is not an Item, Group or Function
../lib/Traits/YDYRCatalogFunctionJobTraits.ts:
[]
[08:27:31] 'userGuide' errored after 2.44 s
[08:27:31] Error in plugin "user-doc"
Message:
    Mkdocs exited with an error.
Details:
    domainThrown: true

and than I used the npm run build-docs

tephenavies · 2021-01-21T23:25:34Z

@draugnim Are you using python 3 (I recommend 3.7, but I think 3.6 or 3.8+ should work)? And with all of the dependencies in requirements.txt installed? Mkdocs which we use to build our markdown docs into a website requires Python.

…bpack config

draugnim · 2021-01-29T12:12:31Z

@steve9164 thanks for the info. I installed python 3.7 and all the dependencies as you suggested but still i got the following error:

[11:47:56] 'build-for-doc-generation' errored after 55 s
[11:47:56] TypeError: cosmiconfig_1.cosmiconfigSync is not a function
    at new ForkTsCheckerWebpackPlugin (C:\Srdjan\Programming\promap\packages\prointer-gis\node_modules\fork-ts-checker-webpack-plugin\lib\ForkTsCheckerWebpackPlugin.js:28:44)
    at configureWebpack (C:\Srdjan\Programming\promap\packages\prointer-gis\buildprocess\configureWebpack.js:273:9)
    at module.exports (C:\Srdjan\Programming\promap\packages\prointer-gis\buildprocess\webpack-docs.config.js:32:10)
    at buildForDocGeneration (C:\Srdjan\Programming\promap\packages\prointer-gis\gulpfile.js:142:73)
    at build-for-doc-generation (C:\Srdjan\Programming\promap\node_modules\undertaker\lib\set-task.js:13:15)
    at bound (domain.js:426:14)
    at runBound (domain.js:439:12)
    at asyncRunner (C:\Srdjan\Programming\promap\node_modules\async-done\index.js:55:18)
    at processTicksAndRejections (internal/process/task_queues.js:79:11)
[11:47:56] 'user-guide' errored after 55 s
[11:47:56] 'docs' errored after 55 s

I figured that cosmiconfig v5 is beeing used but the code in \node_modules\fork-ts-checker-webpack-plugin\lib\ForkTsCheckerWebpackPlugin.js is written for cosmiconfig v6.

In package.json fork-ts-checker-webpack-plugin version 5.0.7 is referenced.

I manually installed cosmiconfig v6 and was able to build the docs then with npm run gulp docs

…ing documentation.js

rowanwins added 4 commits July 30, 2020 08:49

start work on doc generation process

8d5f550

functioning

a6b2610

looking reasonable

50b5170

minor tweaks to template

13f45af

rowanwins mentioned this pull request Aug 25, 2020

Examples for CatalogItems #4220

Closed

tephenavies added 6 commits September 23, 2020 01:13

Update mkdocs to current version

fcad58d

Update WMS region mapping documentation with deprecation warning

29fb36a

Remove unnecessary renaming of README.md files

c123f66

README.md are now turned into index.html by mkdocs (in the absence of an index.md)

Guess that Travis has Python 3.6 available 🤞

5df239e

Remove double-documented JSDoc that's screwing with docs

8e74514

Show generated docs for additional models

d1b4f5a

soyarsauce added 2 commits September 23, 2020 15:13

Merge remote-tracking branch 'origin/next' into mobx-docs

e677c0e

# Conflicts: # .gitignore # lib/ModelMixins/Cesium3dTilesMixin.ts # lib/Traits/WebMapServiceCatalogItemTraits.ts

Fix bad merge

6c6d337

tephenavies added 3 commits September 23, 2020 16:19

Change JSDoc to normal comment to avoid wrong doc generation for priv…

bbe996b

…ate property

Move Python requirements for building docs to appease Netlify

0c809ec

Fix incorrect docs links to new models

88ead00

tephenavies previously requested changes Sep 25, 2020

View reviewed changes

Update .travis.yml

806838b

tephenavies mentioned this pull request Sep 29, 2020

Auto deploy v7 & v8 docs #4811

Closed

9 tasks

Sergio Conde Gomez and others added 2 commits October 1, 2020 11:33

Update Basemaps URL and attributions

e25cfd8

Merge pull request #4821 from TerriaJS/fix-ci

e14d2ea

Fix CI PR build for external contributors

soyarsauce and others added 4 commits October 2, 2020 12:57

Merge branch 'master' into mkdocs-update

673f028

Merge pull request #4824 from skgsergio/update-basemaps-url-and-attri…

ad74ee9

…butions Update Basemaps url and attributions

changes as per feedback

bb76468

retry the gitignore

7c188ed

tephenavies added 4 commits November 27, 2020 18:29

Add some quick v8 fixes

4937328

Make mobx-docs its own Netlify app

344ec7b

https://app.netlify.com/sites/terriajs-docs-v8/deploys

Quote netlify env variables

27ab78f

Add catalog functions

c0bfa11

Add docs for References and a few more doc generation changes

52675b5

tephenavies added 2 commits January 14, 2021 15:20

Merge remote-tracking branch 'origin/next' into mobx-docs

b6b7271

Merge remote-tracking branch 'origin/next' into mobx-docs

e9f1e33

KeyboardSounds reviewed Jan 14, 2021

View reviewed changes

Merge remote-tracking branch 'origin/next' into mobx-docs

f77d9e9

tephenavies added 2 commits January 22, 2021 10:39

Fix formatting of multiline Trait descriptions and remove vue from we…

4830ccf

…bpack config

Update docs linking to issue

7475b84

tephenavies linked an issue Feb 1, 2021 that may be closed by this pull request

Make auto-generated docs for TerriaJS version 8 #4502

Closed

4 tasks

tephenavies mentioned this pull request Feb 15, 2021

Make auto-generated docs for TerriaJS version 8 #4502

Closed

4 tasks

tephenavies added 3 commits March 16, 2021 19:03

Merge remote-tracking branch 'origin/next' into mobx-docs

7a77aff

Re-add vue config to docs webpack. Used to placate webpack when build…

0ccec9f

…ing documentation.js

Update react types version to avoid collisions

22c5020

tephenavies enabled auto-merge March 16, 2021 10:22

tephenavies merged commit db89751 into next Mar 16, 2021

tephenavies approved these changes Mar 16, 2021

View reviewed changes

tephenavies deleted the mobx-docs branch March 16, 2021 13:47

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Mobx docs #4666

Mobx docs #4666

rowanwins commented Aug 25, 2020 •

edited by tephenavies

Loading

tephenavies commented Sep 14, 2020 •

edited

Loading

soyarsauce commented Sep 23, 2020

soyarsauce commented Sep 23, 2020

tephenavies commented Sep 23, 2020 •

edited

Loading

tephenavies Sep 24, 2020

tephenavies Sep 25, 2020

rowanwins Oct 2, 2020

tephenavies Sep 25, 2020

rowanwins Oct 2, 2020

tephenavies Oct 2, 2020

tephenavies commented Oct 2, 2020

tephenavies commented Nov 27, 2020

zoran995 commented Dec 7, 2020

zoran995 commented Dec 7, 2020

tephenavies commented Jan 14, 2021

draugnim commented Jan 18, 2021

tephenavies commented Jan 19, 2021

draugnim commented Jan 19, 2021 •

edited

Loading

tephenavies commented Jan 21, 2021 •

edited

Loading

draugnim commented Jan 29, 2021

Mobx docs #4666

Mobx docs #4666

Conversation

rowanwins commented Aug 25, 2020 • edited by tephenavies Loading

What this PR does

Learnings

Checklist

tephenavies commented Sep 14, 2020 • edited Loading

soyarsauce commented Sep 23, 2020

soyarsauce commented Sep 23, 2020

Previous (next)

mobx-docs

tephenavies commented Sep 23, 2020 • edited Loading

tephenavies Sep 24, 2020

Choose a reason for hiding this comment

tephenavies Sep 25, 2020

Choose a reason for hiding this comment

rowanwins Oct 2, 2020

Choose a reason for hiding this comment

tephenavies Sep 25, 2020

Choose a reason for hiding this comment

rowanwins Oct 2, 2020

Choose a reason for hiding this comment

tephenavies Oct 2, 2020

Choose a reason for hiding this comment

tephenavies commented Oct 2, 2020

tephenavies commented Nov 27, 2020

zoran995 commented Dec 7, 2020

zoran995 commented Dec 7, 2020

tephenavies commented Jan 14, 2021

draugnim commented Jan 18, 2021

tephenavies commented Jan 19, 2021

draugnim commented Jan 19, 2021 • edited Loading

tephenavies commented Jan 21, 2021 • edited Loading

draugnim commented Jan 29, 2021

rowanwins commented Aug 25, 2020 •

edited by tephenavies

Loading

tephenavies commented Sep 14, 2020 •

edited

Loading

Previous (`next`)

`mobx-docs`

tephenavies commented Sep 23, 2020 •

edited

Loading

draugnim commented Jan 19, 2021 •

edited

Loading

tephenavies commented Jan 21, 2021 •

edited

Loading