Improve documentation

[ghost]

Hi Nicolas, and thanks for this package. I'd like to help you improve this package as I'd like to use it next year with my students.

This PR is a proposal for a better documentation. I added a makefile to publish doc to gh-pages branch with the command make publish-doc see my repo for a demonstration.

• I refactored the doc folders, and moved res folder to doc/Images.
• md files are now part of jsdoc as tutorials.
• the graphics.md tutorial have been converted to an ipython notebook converted during build as a html file with make js-doc.

To add a new tutorial, you can now add:

• a md file to the tutorials folder
• or a ipynb file to the ipynb folder.

What do you think about these changes?

[n-riesco]

Please, call me Nico. First of all, thank you for helping with the documentation. It is very much welcome, but before it's too late, let discuss the goals.

I have quickly been through your pull request (I hope I didn't missed anything important). I see you want to:

• use jsdoc to generate all the documentation
• publish the documentation in https://n-riesco.github.com/ijavascript
• use .md files in doc/tutorials/ and .pynb files in doc/pynb/ to generate tutorials
• use folder doc/Images/ to store images (more on this further below)

The pull request, as it stands now, requires the following additional dependencies:

• ghp-import
• make
• cp
• rm

Here are some initial comments:

• I would like to avoid additional dependencies (if possible). I think npm run, node and git could be enough. (I have no experience with github.io to be able to judge the need for ghp-import; I will come back to you on this).
• I would like to keep file and folder names in small letters; that is doc/images better than doc/Images
• Given that the tutorials are kept in doc/tutorials and doc/pynb, wouldn't it be easier to keep the image files there too?

I think there is a broken link the root README.md (it links directly to a .pynb file).

I've noticed that the navigation bar in http://benjaminabel.github.io/ijavascript/ overlaps with some of the tutorials.

One last thing. I found difficult to read some of the commits (the main changes were hidden amongst a large number of deleted files).

---

Let's think how we can take this forward:

1) The first thing I ask all the contributors is to update the AUTHORS file to confirm that: 1) they are the copyright holder of their contributions and 2) they agree for their contributions to be distributed within IJavascript under the terms in the LICENSE file.

2) I would also like to agree what the folder layout is going to be: doc/ (all the documentation except the root README.md goes here) doc/README.md (README in n-riesco.github.com/ijavascript) doc/tutorials (.md tutorials) (how about doc/tutorials-md?) (is it possible to have .md and .pynb files in the same folder?) doc/pynb (.pynb tutorials) (how about doc/tutorials-pynb?) doc/images (is it necessary?) doc/output (temporary folder used to update https://n-riesco.github.com/ijavascript)

3) Move the functionality in makefile to package.json (I need to familiarise myself with the procedure to update https://n-riesco.github.com/ijavascript to be able to make a decision about gph-import)

4) Solve issue with jsdoc navigation bar overlapping with some of the tutorials.

Please, let me know what you think.

[ghost]

Thanks for your reviews, I knew that I was adding some dependencies to the repo. I'm not really a node specialist, so I used what I know. I think we could avoid using make and other unix tools, but use python shouldn't be too off-topic, as ipython and jupyter are python tools and users and devs should be in a python available environment.

There is one important point in the way doc is published which makes ghp-import really usefull. The doc/output directory doesn't stay inside the version control, when generated locally, gh-import move it to the gh-pages branch which is then automatiaclly accessible via http://n-riesko.github.io/ijavascript/.

[ghost]

Given that the tutorials are kept in doc/tutorials and doc/pynb, wouldn't it be easier to keep the image files there too?

I used a doc/images folder and created symbolic links to the other folders inside docs to keep all in one place.

[n-riesco]

Hi Benjamin,

I've created a branch named issue-14 with your pull request. I hope this will help us collaborate until the PR is ready to merge with master.

Last night I experimented a little bit with the gh-pages branch and my feeling is that we can make do without ghp-import. I want to try this first. I will let you know how I get on.

[ghost]

Hi Nicolas,

doc/tutorials (.md tutorials) (how about doc/tutorials-md?) (is it possible to have .md and .pynb files in the same folder?)

Now all tutorials are in the same place, and the html files created with nbconvert were added to .gitignore

[ghost]

I've created a branch named issue-14 with your pull request. I hope this will help us collaborate until the PR is ready to merge with master.

Do you want that I close this PR and create another one pointing to the new branch issue-14?

[n-riesco]

Yes, please. I think it would help me keep the branch in sync with your changes.

[n-riesco]

Hi Benjamin,

I've pulled your latest commits into branch issue-14.

I've also converted the notebooks to version 3 format (to ensure compatibility with older versions of IPython).

And I've removed the Makefile and the dependency to ghp-import.

Now, to generate the docs it's enough to run:

npm run doc

and to update the gh-pages, I can run:

npm run doc:publish

and you can either update the doc:publish script in package.json to use your own repository or run:

node scripts/doc-publish.js doc/output https://github.com/benjaminabel/ijavascript

---

I think the next issue we should address is to fix the JSDoc layout and avoid the overlap between the navigation bar and the tutorials.

Another thing I would like to do as well is to separate the documentation intended for developers from the documentation intended for users.

[ghost]

Hi Nico, really nice job, it seems that node is much more powerfull than I thought! Now I'm going to update informations about documentation inside the root README file. To address the css problems it's possible to use docstrap which use bootstrap like ipython notebook. Sure, it's a dependencie, but a npm one, if you want to avoid it, it's also possible to work on local jsdoc templates. Tell me, I'll can give a try.