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 :)