Comments (7)
I've added some documentation to the index.js file. and did an initial build. You can use that as example. None of the tests are documented yet.
Should be live here:
https://justingosses.github.io/wellio.js/docs/
from wellio.js.
Caveat: While I have documentation experience it is not with Sphinx nor with Javascript documentation.
Observations:
- I did a scan of the various tools available: Both Documentation.js and Sphinx.js look like solid choices. Both have been around for a while and are active with recent issue and pull request activity. Their licenses are ICS and MIT respectively.
- It is a plus for Sphinx.js that you have Sphinx experience.
- It looks like both Documentation.js and Sphinx.js are using JSDoc format underneath. The JSDoc format seems to be the most standard Javascript documentation format. So regardless of a tool decision, updating the code with JSDoc documentation style and tags has to be done as some point.
https://www.npmtrends.com/documentation-vs-esdoc-vs-jsdoc-vs-sphinx-js
https://jsdoc.app/about-getting-started.html
My 2 cents...
It might be best to to do an iteration of revising the code comments to adopt the JSDoc standards and style as well as iterating the content before committing to documentation generation tool.
DC
from wellio.js.
I tried documentation.js on another project. It is pretty easy to get started with but it seems JSDoc has a limitation that config files for it can't find functions that are module exports. As such, it will include those files in the documentation but you can't structure the order they appear or include additional information around where they appear. They only appear at the bottom of the documentation page in the order they're discovered in the source files, which is okay but not exactly ideal.
Hence, I'll try to do some research into non-Doc.js based documentation libraries that can handles functions that are module exports.
from wellio.js.
Seems like pretty much everyone uses JSdoc based documentation for JS. Problem isn't quite as bad as first though though. Started to put in some JSdoc style function descriptions as described here https://github.com/documentationjs/documentation/blob/master/docs/GETTING_STARTED.md
Will add documentation build script to github actions eventually.
from wellio.js.
If you could implement an example JSdoc documentation of one function in a Wellio.js project file and post it on a draft branch?
That would give me (and maybe others) a project template to update the other Wellio.js function documentation to JSdoc format.
DC
from wellio.js.
Great, I'll use the example going forward.
Thanks
DC
from wellio.js.
Stale issue message
from wellio.js.
Related Issues (20)
- Test Failure: las2json : test_v2_inf_uwi_leading_zero_value.js HOT 1
- Should wellio.js send a non-blocking error message to console when it sees a missing section , like section A, that it can work around? HOT 1
- Allow time colons before colon delimiter HOT 1
- push changes to new version of wellio on npm: reminder for Justin HOT 2
- double check that recent updates to npm for v 0.1.6 didn't break any observable notebooks or demos HOT 3
- split read_json() function into 2 parts: one that uses fs and one that takes dict
- BUG: fs for file uploading works with node.js but not in jupyter notebook HOT 8
- Fix tests for reading lasio and wellio json files
- Update package-lock.json : ajv-cli, minimist
- Duplication of demo page between wellio & wellioviz? HOT 2
- clean up lasio <-> wellio.js notebook & mention in README HOT 1
- Another malformed LAS file example HOT 1
- demo has some weird state issue HOT 1
- more malformed LAS files from USGS to handle, mostly florida HOT 19
- Need to fill out 3 sections in docs HOT 1
- looks like download function is missing from main.js in docs folder HOT 1
- fs is being called and fails when it shouldn't be in wellio when used by wellioviz within a REACT app HOT 1
- Add instructions to DOCS for how to clone and install locally for making changes to contribute! HOT 1
- Possible problem with wellio.loadLAS("well.LAS") HOT 3
- add link to https://github.com/JustinGOSSES/wellio-playground once GitHub can accept browser edits again
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from wellio.js.