-
Notifications
You must be signed in to change notification settings - Fork 362
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Mobx docs #4666
Mobx docs #4666
Conversation
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)
@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
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 |
package.json
Outdated
@@ -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", |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
|
||
## Properties | ||
|
||
"type": "undefined" |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Looks like this type has been ascertained incorrectly
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Seems to be something to do with WPS but haven't quite worked out what yet....
mkdocs.yml
Outdated
@@ -0,0 +1,81 @@ | |||
site_name: TerriaJS |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd prefer to keep this file in doc/
. What's the reason to pull it out to the root?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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 🤷♂️
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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
@rowanwins Any chance you can advance this? |
…butions Update Basemaps url and attributions
Switched all build outputs to be in |
Should we document the usage of search providers (i.e. proper config to set them in TerriaMap), I am working on Esri geocoder support |
Also, can we add the required next to the required parameters in doc? |
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. |
I was not able to build the docs with 'npm run build-docs '. The error was:
I manually created the 'doc/connecting-to-data/catalog-type-details' folder and the build passed. |
Hi @draugnim. Thanks for letting me know. |
I first tried with that function but it failed with
and than I used the |
@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 |
@steve9164 thanks for the info. I installed python 3.7 and all the dependencies as you suggested but still i got the following error:
I figured that cosmiconfig v5 is beeing used but the code in 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 |
What this PR does
Fixes #4502
This PR does various docs things for the
next
branch.mkdocs.yml
catalog-items.md
andcatalog-groups.md
pagesmkdocs.yml
Learnings
I'm using documentation.js as it has a node API for retrieving jsdoc style stuff from files.
I ran into issues with reading jsdoc from
lib/Models
so ended up throwing things inlib/Traits
which seems to kinda be workingI went for a table-based layout for scan-ability given the large number of traits most models have.
Things to do
npm run publish-doc
needs updating I think...Checklist