Node_Editor_Framework
Node_Editor_Framework copied to clipboard
Seneral
Node_Editor documentation
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.
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.
@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).
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).
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.
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.
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. ^^
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
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;)
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.
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.
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
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;)
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;) )
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. ^^
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.
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;)
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?
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
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?
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...
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) ;)
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?
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.
