Documentation

[shumway]

I spent about an hour evaluating hdf5.node, and didn't make much progress. There some misdirection in the README.md and the link to the api appears to be out of date. Looking at the recent commit history and test suites is helpful.

I would suggest two concurrent steps to improve the documentation:

1. Update the README.md to be similar in style and quality to popular node projects. The README.md on express looks like a good model. Having README sections Installation, Features, Philosophy, and Docs & Community would be helpful for users and contributors. It's important to say up front what hdf5.node does and does not do.
2. Discussion forum on Gitter or Google Groups. Searchable discussion forums outside of issues could attract new developers, help focus the scope and goals, and nucleate new ideas. I've used Slack and Google Groups on other projects, but Gitter might be the best match for this project.

If other developers think this is a good idea. I can jump in and do this. I (or someone else) should probably set up the discussion group first, since I have some questions about the existing README.md file. I also need to make sure I understand the philosophy and vision behind this project. I don't want to add any additional confusion about the scope or goals.

[rimmartin]

The readme.md is out of date with the splitting of the core from my experiments and reference viewer.

Did you follow the link to http://rycole.com/hdf5.node/? It will need some updating or additions.

I'd've cut readme.md down quite a bit and published again but the changes to hard-coded paths in binding.gyp https://github.com/HDF-NI/hdf5.node/blob/master/binding.gyp#L3 to native hdf5 libs is problematic for users who don't install that way; In the past I had an environment variable
export HDF5_HOME=/home/roger/NodeProjects/hdf5
to set it http://rycole.com/hdf5.node/doc/install-setup.html

Trying to resolve the issue; this does't work when hdf5.node is a sub module of another project yet

nodejs/node-gyp#893

[rimmartin]

Ah when the project was moved under the HDF-NI organization the gh-pages https://github.com/HDF-NI/hdf5.node/tree/gh-pages automatically republished! Nice of github to do that:-)

http://hdf-ni.github.io/hdf5.node/

so the link can be changed

[shumway]

Nice! This is making more sense now. The rycole.com domain and the out-of-date “Getting Started” page that refers to ./lib/application.js really threw me when I first looked at it. @vincent-tr 's #18 commit message on the libs directory got me back on track. I can do some small updates to the master README.md, then mostly go through the gh-pages to see that all the tutorials work correctly in the current version.

Regarding building and runtime: HDF5_HOME is most convenient when it works. Because I did an npm install hdf5 directly that worked great for me. As an additional complication, it's probably more convenient to link to static libraries, since that's possible in node. Setting LD_LIBRARY_PATH has always been a pain with the Java wrappers and tools.

[rimmartin]

Oh before going too far github sent me a notice they will no longer be supporting 'redcarpet' Markdown engine but the 'kramdown' engine. Not sure how different these two formats are.

Also this project uses node-pre-gyp and I have prebuilt versions up on amazon S3 which get pulled by npm install hdf5 or when included in another package as a module. Many users don't need native compiling at all.

Static linking would solve one problem; I was hesitant over licenses and because I didn't know if there could be an incompatibility to a user's h5 files across versions; although hdf5 has been very stable. Have to ask more people how this would effect them. It definitely would make the prebuilts matrix smaller

[rimmartin]

A web socket layer and the application/hdf5 viewer/editor are moving to their separate projects under https://github.com/HDF-NI organization. You have access to it

You and @vincent-tr now have write access to hdf5.node as well(discovered I can change settings now that @ryancole moved it to HDF-NI.

Had all my hdf5 interface efforts in one project while I was experimenting and was happy when @vincent-tr decided to help split the core hdf5.node as a pure API so other projects don't need my extra or experimental dependencies such as binaryjs[which is being replaced] and koa etc.

I have browser tree views and editing which I'm rewriting ad putting into other projects. Had table data going to an ethercalc spreadsheets.

Now with a rewrite I'm making a web socket endpoint api to provide access in browser pages to hdf5 data.

[rimmartin]

Also am thinking of a separate image layer for sending large images to the browser. Geo and weather and map data

[rimmartin]

npm install  --build-from-source --hdf5_home_linux=<pathtoyourhdf5install>

does work; also if a dependent project puts the --hdf5_home_linux switch on its install line it works from there too.

We cut down the readme.md for this core project, update links and I'll publish it to npm and provide the prebuilts for mac, windows and linux

[rimmartin]

I tested changing to kramdown markup in another project https://github.com/rimmartin/saxon-node/blob/gh-pages/_config.yml#L46

Change most needed was a linefeed before blockquotes

[shumway]

OK, I now have jekyll running locally and I'm seeing some of those formatting issues with kramdown. I'm working on that now.

[rimmartin]

Ah good. codeblocks are different too. I'll test more on linux and in the morning build on windows and mac to be ready to publish and upload the prebuilts.
./bin/jekyll-page
Is a little helper script for setting up new pages; .md is tagged on automatically

I had started with https://github.com/bruth/jekyll-docs-template

Let me know what else you may need

[shumway]

I updated the readme.md. Please leave me feedback if there are any problems with my edits. I added badges to the top, reorganized headings a little, then removed the description of the viewer.

Sorry for the multiple commits. I'm out of practice with git, then I made a mess when I tried to amend my missing edit. It was a simple edit (deleting the viewer description in the readme), but the log got botched by splitting into three commits.

[rimmartin]

Good going! Ill look thru..

We should be able to publish to match the docs soon

[rimmartin]

For users who don't have hdf5 libraries installed at the path of https://github.com/HDF-NI/hdf5.node/blob/master/binding.gyp#L3

the hdf5_home_linux is now a switch:

$NODE_HOME/bin/npm install  --build-from-source --hdf5_home_linux=/home/user/NodeProjects/hdf5

and in dependent projects it also passes thru

cd /home/user/NodeProjects/hdf5.ws
$NODE_HOME/bin/npm install  --hdf5_home_linux=/home/user/NodeProjects/hdf5

and there is a different one for mac and windows which work similarly.

Where we talk about building we can reduce questions by stating this clearer than what I just did

[rimmartin]

Published to npm