Online documentation

[ssssam]

Hello,

This PR adds online documentation for Hydra using GitHub Pages.

You can see more or less what they look like here: https://ssssam.github.io/hydra/, it's identical to this PR (apart from the bits that say "Sam Thursfield fork" of course :)

If you merge this branch to master and configure the repo to serve Pages from the 'master' branch docs/ subdirectory, it should magically appear at https://ojack.github.io/hydra/.

I'm happy to revise the PR a bit based on feedback, although bear in mind i'm not much of a web designer.

In this branch I did some minimal editing of the existing docs (basically to deduplicate them into a single file), and added a simple Jekyll configuration using the minimal-mistakes theme. I chose that theme because it supports a sidebar navigation menu, I didn't find any others which support that.

[ojack]

Hey this is really cool! I would like to include this documentation in the existing site at https://hydra-editor.glitch.me, rather than create a separate website. I think it could be another button in the top menu that pulls up the documentation. What do you think / would you be interested in working with me to integrate the two?

[ssssam]

I chose GitHub Pages because it seemed easiest, but I can see it makes to integrate it into the existing editor instead. Let's at least scope it out and see how hard it would be :)

I guess we find a tool that can run as an npm script to generate .html from the .md files, then serve that as we already serve the other content. We could still use Jekyll, but it pulls in a whole Ruby dependency chain, so I think looking for a similar library on https://www.npmjs.com/ would make more sense instead. Do you have any preference about that?

And how would we integrate the docs with the display ... in the existing popup dialog? That's simple but it means you can't edit the code while reading the docs.

[ojack]

Yes good idea to scope it out!

I am going to put all of the things I am thinking here, doesn't mean that an initial implementation has to include all of these things, but rather a roadmap to work towards.

1. Markdown documents can be loaded within javascript: https://www.npmjs.com/package/marked and the html added to existing html elements on the page via javascript.
2. Ideally all of the documentation of each function should be automatically generated from the composable-functions.js file. This file could have fields for description and examples. (these edits need to happen within the hydra-synth module). That way the documents most reflect what is currently available in hydra.
3. I agree that you should be able to see the code while reading the documentation. I think the easiest way would be to make the code stay up even when the popup is up, and the existing popup draggable and dockable.
4. Clicking on an example loads that code in the editor and renders it.

This branch by @alvarobyrne is a good starting point for all of these things: https://github.com/toplapbogota/hydra/tree/documentation?fbclid=IwAR38BIrUAXtEIF5t4r6lqp27yEMMSYrfpTh2jhueCbKNUbYJ1blHx7p1zKA It is missing a more general documentation, as well as integration with the popup window, but has basically everything else. I haven't had time to work on this aspect in a while so unfortunately haven't been able to integrate yet :)

[ssssam]

Thanks for the info! And for the link to Alvaro's branch which is very useful to get an idea for how things should work.

Making the help popup draggable and dockable would be great. I think we should use a 3rd party library for that if possible - I found a few that support draggable dialogs, but none that support dockable ones. My current favourite based on 10 mins googling is jBox.

Here's a proposed list of work items which I think will bring us close to your design. Let me know what you think!

1. Move function documentation from docs/*.md into hydra-synth/src/composable-glsl-functions.js. Write a simple script to generate the docs/funcs.md file from that. We could commit the generated file to Git at this point, so everyone can still read the documentation online.

2. Add jBox library and make the help popup draggable.

3. Add marked library. Insert the content of the generated funcs.md file in the help dialog.

After these we'd have a good proof of concept, and we could think about

• how to make the docs easy to navigate
• how to integrate the examples with the editor.
• performance - I suspect there'll be performance issues with loading the entire documentation into the DOM, so perhaps we'd want a more sophisticated approach that loaded docs for one function at a time, on demand.

[ssssam]

This PR isn't going to be merged. I've moved the planning info to https://github.com/ojack/hydra/issues/58