Node_Editor documentation

[pmhpereira]

PDF shouldn't be the only format of distribution for the documentation.
It's hard to edit (only the one - you - with the source file can edit it) and it lacks version control because it is a binary file type.

I think a good alternate way would be to have GitHub pages set up, with the documentation in HTML. The PDF files in this repository would be a "print" of those files.

[groud]

Hi !

I have seen a lot of project using the markdown language.
https://github.com/fletcher/MultiMarkdown/blob/master/Documentation/Markdown%20Syntax.md

Github natively display that kind of documents. They are faster and easier to write than native HTML documents. Also, they can be easily transformed into HTML format thanks to tools (like dillinger.io, but I think non navigator-based tools exist).

I would recommend to create a "documentation" folder with a set of markdown files.

[pmhpereira]

@groud, the issue here is that when people download this plugin to use with Unity, they should have access to offline documentation.

Markdown needs some sort of engine to be rendered. It would render well here on GitHub, but not locally. It also doesn't support text colors or alignment, and all the images are downloaded from the internet (you can't embed them directly like in PDF).

[groud]

You are right on some points.
The Markdown language is meant to be compiled, usually to HTML format.
Keeping only the md files with no "compilation" is actually not pertinent.

However, Markdown and HTML are two languages that can access local images, no Internet access is needed to include image (a folder next to the source file is enough).
Depending on the compiler, some Markdown processors can also include inline HTML, and therefore text colors. :)

What I would suggest, is to use the md language to compile a HTML documentation. Which will be used as github pages, but also as a offline HTML documentation (As a compiled Javadoc, which does not need Internet access).

[pmhpereira]

That's actually what Node.js and React does, so it surely is viable. But it would need some sort of automation to rebuild the HTML files when one of the MD files is updated. Or @Seneral would have to do it by hand once a week or so. :D

master branch: /docs would contain all the individual Markdown files
gh-pages branch: would contain all the compiled HTML files from Markdown and custom Javascript / CSS if needed (this way, the documentation is automatically self-hosted and can be linked directly to with http://baste-raingames.github.io/node-editor)

When creating Release distributions (what people would directly download), it would have the HTML files instead of the Markdown ones for the documentation, so it could be read off-line.

[groud]

Yes, that's seems perfect to me ! :)

[Seneral]

I actually started already to create the HTML Documentation. I first passed it through a auto creator from the PDF format which resulted in an absolute mess:(
I do not really like MD very much due to some limitations mentioned above...
I can provide the source document next to the pdf, too, of course.

[groud]

I know that MD has some limitations (I have to admit it is not meant to create very fancy looking documents). But well, several compilators are able to include html code into the MD language, so that you can create more interesting shapes.

However, the most important thing is that MD is far easier to maintain than HTML (No missing

, or, inconsistent HTML tags usage, etc... ). It is readable, and does not take long time to update.

As the documentation is usually a tedious job, I usually prefer to keep such it simple. ^^

[pmhpereira]

Reference:
https://github.com/nodejs/node/tree/master/doc - Markdown source files
https://github.com/nodejs/node/tree/master/tools/doc - Markdown to HTML compiler

Example:
https://github.com/nodejs/node/blob/master/doc/api/documentation.markdown
https://nodejs.org/api/documentation.html

[Seneral]

Thanks, I'll take a look at that later when I come back!

[Seneral]

I just added the html aswell as odt source file for the documentation in fc180bc.
I also created the online documentation in the gh-pages branch. You can check it out here. What do you think?
http://baste-raingames.github.io/Node_Editor/
Feel free to edit the index.html in gh-pages if you want to improve something;)

[pmhpereira]

Cool!
Are the ODT and PDF files still needed, though?
Since there is an HTML version available, it can be distributed directly with the source code and be read offline.

[Seneral]

Probably not. I kept it because you we're mentioning to keep it as a print above;)
Anyway, I'll try to make a version with a bit more structue, like a hierarchy on the left to browse them and having only the selected section on the right. My html-skills are not that advanced (tbh pretty basic) so I hope there is a similar generated GitHub page already;)
I would of course keep this all-in-one version though for offline purposes.

[groud]

I just found this: mkdocs
This might be what they used for the node.js documentation.

[Seneral]

That looks really great, no need to build conplex html sites and concerning about the style anymore:D But that means yet another conversion.... I might take a look at doing that if I find sone free time

[groud]

I can handle that if you want :)

[Seneral]

Cool, thank you! :) I guess automation could lift alot of work off here, atleast by replacing the simple tags like b, i, u, etc. with their MK counterparts;)

[groud]

See #59

[Seneral]

Looking good so far:) Might be better to make a seperate branch though to work on the documentation (additionally to the gh pages one which hosts the online documentation). I can setup that tomorrow if thats ok.
Based on the front page of that project you linked it looks very easy to make a site that has stuff like a 'page tree' to browse the different pages. We would probably use something like that and split the documentation up for that structure, so we would also need to rewrite some chapters (the preface and conclusion seem out of place without content inbetween;) )

[groud]

Well, I do not think we really need a separated branch for the doc, as it is supposed to evolve with the software (It is not a different version, like the "master" and "develop" are supposed to be)

However, the main question here is how we distribute the documentation.
In my opinion we should let the documentation sources into the master/develop branches, and only keep the online documentation.
For me it is not necessary by now to keep up to date both an online and an offline version.

However, I'll stick to the majority opinion. ^^

[WeslomPo]

Why you do not want to use wiki in github?

[groud]

Hum, I just find out that the Github wiki is in fact a git repository.
This seems to be a good idea for me, we could move every documentation-related sources and export scripts into this git repository.
See here.

[grimmdev]

👍 👍

[Seneral]

Nice indeed! But as I said, I wont be able to do anything of this. If you want to do this, I'm sure @Baste-RainGames can make you a contributor so you can create branches and the wiki;)

[Seneral]

I made a modified version of groud's mkdocs version and will make a pul request for that:)
While doing that we could chose a style (preset). These are my favorites (wel there are not too many, I chose about half of them):
Yeti:

Bootstrap:

Cerulean:

Cosmos:

Simplex:

Slate:

Ideas?

[groud]

Other themes can be found there:
https://github.com/mkdocs/mkdocs/wiki/MkDocs-Themes
The bootswatch one seems not so bad (The font and huge title are cool :) )
I also teste the material one, the color is configurable and you can add a logo

[Seneral]

Oh nice, didn't see that!
Btw I just made a pull request in your repo for the doc here
Btw what does that 'check failed' mean?

[Seneral]

Btw, setting this live on gh-pages when we merged develop into master as alot of the documentation is dependant on the changes we made since the last (first) release...

[Seneral]

So, after long silence, I think we should prepare for making them go live. I made some adjustements and included most recent changes but I don't know exactly if we came to a conclusion where to put the docs - gihub pages, the repo wiki or readthedocs?
If that is done, I would start the process of merging develop into master. I'm at the end of my vacation job and schools starting again, so I'll have more time and energy to do all this (hopefully) ;)

[Seneral]

So, the online documentation is now updated with the mkdocs version which is also up-to-date with the develop branch:)
How it works:
develop/docs still hosts the sources and those have to be manually updated and pushed to gh-pages regularily. I considered using ReadTheDocs but in the end chose gh-pages even though it does mean I need to update it manually.
What do you think?

[Roni1993]

The Documentation is a good beginning sofar. Though i´m having problems to actually understand the overall Framework Structure. it might be good if you´d add some sort of graphical overview referencing the different parts.

[Seneral]

That's what 'Framework Overview' is supposed to do, but as you see it's not really developed yet...
But that might be a really good idea, though I'm not quite sure how it would look like... I'll think about it!

[Seneral]

Have a good concept by now, might post a first version soon:)

[Seneral]

First Version, sketched online. What do you think? Any more details I should definitely include, or connections I should explain?
I would go into more detail about each of those elements in text form, I think that is the best way to approach it...
Hope this gives you a decent overview:)
Also notes that for the documentation version I would find a better way of visualization...

[Seneral]

Maybe a bit better:

Good enough for now;)

[Roni1993]

hmm, honestly this overview didnt help me much but that might be because it lacks the context and an explanation. right now its also kinda hard to make suggestions since i didnt grasp the concept of the internals sofar. Maybe i can give you some better feedback as soon as i´ve got an better overview over the framework :)

[Seneral]

Yeah I understand you... Thanks for your feedback:) I'll try to write a line or two for each class for a quick overview, maybe I can even somehow integrate it with the graphic...

[Seneral]

How about this?

Framework: Classes including NodeCanvas, NodeEditorState, Node and all NodeKnobs that make up the base object structure of the Node Editor Framework.

NodeEditor: Main class that handles the current canvas and editorState and serves as the main API for users to draw and calculate their canvases.

NodeEditor User: Any kind of user of the framework, be it a full editor or a small calculation script. The main target API for it is the NodeEditor and NodeCalculator and it can receive events from NodeEditorCallbacks.

NodeEditorUserCache: A wrapper for holding, saving, loading and even caching the canvas and it's editorState. It lifts alot of work from custom NodeEditorUsers that need the full power of the framework, although for some users, simply referencing the canvas is enough.

NodeEditorSaveManager: Manager for saving/loading canvases and their editorStates into assets or the scene aswell as creating workingCopies.

NodeEditorCalculator: A system of the framework responsible for traversing the canvas in a specified manner which can be accessed through NodeEditor.

NodeEditorCallbacks: Central system to provide NodeEditorUsers with callbacks of the framework.

NodeEditorInputSystem: Dynamic, attribute-based input system. Searches all script assemblies for new controls, but all default controls are located in NodeEditorInputControls

NodeEditorGUI: Handles GUI skin and most drawing applications like connection drawing. Related utilities include GUIScaleUtility for scaling, OverlayGUI for scale- and runtime compatible popups and RTEditorGUI for additional, runtime editor controls.

Assembly Fetch: Concept of fetching framework extensions from all script assemblies. The class NodeTypes fetches all custom nodes, ConnectionTypes all custom connection type definitions and NodeCanvasManager all custom canvas definitions.

The description would be the next thing to improve but for the starting I think it's ok. But I need feedback from people not familar with the framework structure;)

[Roni1993]

OK, i just read through the description, looked at the diagram/overview and tried to make sense of everthing. I also already took a look into the sourcecode itself so i might be a little more knowlegable than a truly fresh developer.

anyway, basically the overview is not bad but it doenst really serve the developer to understand your system more. it works out quite ok if you read the whole description while closely looking at the overview and trying to make sense of it but i think we can improve on that. I guess the biggest problem i had myself was that the connections inbetween those classes weren't clear.

So a suggestion i would give you is to try to cluster those classes a little bit more by their purposes.
I would visually group those classes like you did with the Framework. Maybe it would also be nice to have some sort of headline for those clases instead of a colored node.
Anyway i "think" i found those five cluster:

Core

Basically i would rename "framework" to Core since i have the feeling that those classes are more or the less the Core of the whole Node_Editor. These Classes represent the Nodes and therefore are kind of the most imporatant part and should get this attention.

Core Extender

The assembly fetch name is kind of missleading/ meaningless. It kind of answers the question "how" but not "why" and as a Developer you usually try to want to know the reason "why" something exists and "what" it does but not "how" it does something.

Canvas management

Here goes everthing that is managing the Canvas.

Saving System

I guess this cluster is self-explanatory. Also i guess this cluster would extend on the Canvas management?

API

"NodeEditor User" seems a little bit confusing as people would likely search for something called "API" as you mentioned in the description. Also i would give the user some more explanation which aspects of the NodeEditor are modifiable from this API

sofar this overview already helped me quite far but for the sake of new developers i'd like to improve it a little more with you :).

[Seneral]

Some great ideas, seems you have much more experience with this, thank you roni:)

Core and CoreExtender seem really solid, don't think I can add something;)

Regarding Canvas Management&SavingSystem:
NodeEditorUser'sare basically only examples, if you develop your own extension seriously/intend to put it on the AS, you'd likely develop an own from scratch or modify them atleast. I would seperate it from the rest and just leave it as an element to show it's relations but not include it as a framework part.
A bit misleading, NodeEditorUserCachesupports the NodeEditorUseras a wrapper for caching, as the name supposes. So it would fall under CanvasManagement. But because of the saving system, there wouldn't be any additional part I would count to Canvas Management... Maybe it's better to merge both CanvasManagement and SavingSystem.

Regarding the API, I think only NodeEditoras the main class, NodeCalculatorand NodeEditorCallbacksdirectly belong to this.

So as NodeEditorGUIand it's utility classes aswell as NodeEditorInputSystemhas no home yet I'd rather make a new GUI related cluster, which also seems quite logic. One minor complaint is that the input system is also active when not drawing the GUI because it drives the calculation system. This will likely change soon though so I'd still group them.

Hope that makes sense. So, I propose these changed 'clusters':
Core, CoreExtender, CanvasManagement, API, GUI

[Roni1993]

Sounds good sofar.
Though i guess i´m still struggeling to understand the whole connections between what seems to be the NodeEditorUser and the node next to it e.g: RTNoteEdior.
Are those related classes or do they just happen to be next to the NodeEditorUser Node?

Also it would be nice to create a description for each of those clusters and use this overview as starting point within the documentation.

[Seneral]

No, they ARE the NodeEditorUser;) As I tried to explain previously, it is a script that makes use of the API in some way (EditorWindow and RTNodeEditor fully, RTCanvasCalculator basic).

Initial Description:

NodeEditor User: Any kind of user of the framework, be it a full editor or a small calculation script. The main target API for it is the NodeEditor and NodeCalculator and it can receive events from NodeEditorCallbacks.

Explanation in my last comment:

NodeEditorUser's are basically only examples, if you develop your own extension seriously/intend to put it on the AS, you'd likely develop an own from scratch or modify them atleast. I would seperate it from the rest and just leave it as an element to show it's relations but not include it as a framework part.

Need a better way to describe them, I see;) Or most probably the word 'User' is irritating...

[Roni1993]

Well then i'd rename them to "API usage example" or something like that.
"User" is kind of misleading as I was thinking of the user itself but not
about that class being the user x)

[Seneral]

Due to the repo transfer the new link to the online documentation is now
https://seneral.github.io/Node_Editor/

[Seneral]

New documentation page:
http://www.levingaeher.com/NodeEditor/
And also started rewriting it to reflect changes of the develop branch:)
Above concept will likely be implemented in the Framework Overview when I get around to do it:)