Skip to content
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

Online documentation #62

Open
wants to merge 4 commits into
base: master
from

Conversation

@ssssam
Copy link
Contributor

ssssam commented Oct 31, 2019

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.

ssssam added 4 commits Oct 18, 2019
The funcs.md file duplicates content from funcs_*.md files.

Commit cca6b79 updated the funcs.md file without
updating the funcs_sources.md file. This commit fixes it.
We should avoid having duplicate content in the repository.

The individual documentation sections will be combined in a static
Jekyll website from now on, so they should still be easy to read.
The site can be viewed locally, if you `gem install jekyll` and then
run `jekyll serve docs/`. (You'll need to edit the first key in
docs/_config.yml for the theme to work locally).

And it can be uploaded into GitHub Pages. The repository will need
to be configured to build GitHub Pages content from the `docs/`
subdirectory of the 'master' branch.
@ojack

This comment has been minimized.

Copy link
Owner

ojack commented Oct 31, 2019

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

This comment has been minimized.

Copy link
Contributor Author

ssssam commented Oct 31, 2019

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

This comment has been minimized.

Copy link
Owner

ojack commented Oct 31, 2019

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

This comment has been minimized.

Copy link
Contributor Author

ssssam commented Nov 1, 2019

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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
2 participants
You can’t perform that action at this time.