initial version of new documentation template [#429]

[setthase]

This is initial version of new theme for documentation.

What do you think about it? 💭

[parasyte]

I want to replace jsdoc3 entirely! This might be the perfect opportunity to start working on #497, instead of spending time on the jsdoc3 template.

[obiot]

@codename- do you have the final result hosted somewhere, it would be easier as this is more a "visual improvement" at the end.

this said, @parasyte is also right, as the objective was to move away from jsdoc3, i'm just concerned about how much it would take though (i'm talking required effort vs capacity) as part of the 1.1.0 branch that I would like to finalize soon now.

So this one could be a "quick" win for a nice refresh while waiting for something more future-proof in the next major version ?

[ellisonleao]

Hey guys another alternative for documentation is the mkdocs written in python. It's still in development but it's promising. http://www.mkdocs.org/

[setthase]

@obiot - it was 1AM here, when I've created this pull request. Currently I haven't visual version... I'll try do something when I'll back to home.

@parasyte - I know that you want to use new documentation tool, but currently you have nothing... And creating that tool will take you quite a lot amount of your time. That's why I was thinking about refreshing a current template a bit.

---

When new documentation tool will be ready we should create a template for it as well as new design of main page. I like melonJS a lot, but I think that people do not even try it because a homepage look and feel like this project could be old.
Take a look at http://phaser.io/ - they look very dynamic and more professional than we - but Phaser is also maintained by small group of fanatics 😉 (as far as I know).

[obiot]

we were supposed to get a new website end of last year, someone came up with a first prototype, we started working on it, and then he vanished.... but yes I do agree that at least the website do need a bit of a refresh.

I think the main difference with phaser is that the phaser author is working on this full time, while on melonJS side we all and only do this on our spare time (i'm mainly working at night on it), so when it comes to priority we often choose features over less "useful' stuff like the website

[obiot]

this said, please put the generated doc anywhere you can (even drop box), so that I can have a look at it adn provide some feedback about it (without merging this into master, and breaking the current doc generation)

[setthase]

Currently I'm at work, and I've got blocked dropbox etc. But you could easily see it just cloning my repository somewhere into disk, checkout to new-jsdoc-template branch and build docs as usual with melonJS. If you can't do this you will need to wait until I'll back to home.

[agmcleod]

http://projects.agmprojects.com/melonjs-docs-template/ uploaded it to here :)

[obiot]

nice !

The first thing I see missing are the actual images from the current template (the images folder get copied together with the scripts and styles folder during generation) :
https://github.com/melonjs/melonJS/tree/master/tasks/jsdoc-template/melonjs/static/images

that would be nice as well to add back the melonJS logo in the header, see here :
https://github.com/melonjs/melonJS/blob/master/tasks/jsdoc-template/melonjs/tmpl/layout.tmpl#L20

else what kind of options/improvements are available through the template ?

[agmcleod]

Also i noticed a lot of the methods are being identified as static.

[obiot]

I noticed that as well, but i was wondering if this was due to a wrong annotation in the source code ?

On 30 juil. 2014, at 20:51, Aaron McLeod [email protected] wrote:

Also i noticed a lot of the methods are being identified as static.

—
Reply to this email directly or view it on GitHub.

[agmcleod]

Could be. I know we're not explicitly stating "static"

[setthase]

@agmcleod - thanks for publishing this out.

@obiot
Regarding images... That was working on my local version; maybe I've forgot push something. About logo - I'll try fit it there, but logo is white as well as navigation bar.

Regarding static methods - that same was with old documentation, see it here for example: http://melonjs.github.io/docs/me.Ellipse.html

[agmcleod]

Oh you're right, I think i've noticed that, but maybe given the newer style it just looked kind of odd.

[parasyte]

@obiot FTR pull requests can be merged into a private branch (on your local repo) without contaminating anything. Then delete the branch when you're done.

[obiot]

@parasyte ohhh, i see , thanks for the tip, I did not know :P

[obiot]

@parasyte having in mind a "quick win" with this update, any suggestion for improvement on the template ?

[parasyte]

@obiot I haven't looked at it yet. Since it is already done, ok. But please don't waste more energy on this. Put the work toward replacing the slow and broken documentation generator.

[obiot]

@parasyte sure, i'm on the same page here, that's why i'm talking about a quick win with a small refresh of the current template :)

[obiot]

@codename- actually we should change the navigation bar to the melonJS green, that would make it much more nice and solve the white logo issue :)

One additional request I would have also (if offered by the current template) is the possibility to add a search field, as I even found myself sometimes "lost" in the documentation (that starts to be quite impressive now in terms of content)

But then on top of the here above comments (logo and missing image), it's good for me !

also for reference :
https://github.com/melonjs/melonjs.org/blob/gh-pages/media/palette.png

[setthase]

@obiot - I didn't know that there is some colours palette! Good to know 👍

About search - you want to search between pages or on currently open?
I'll fix missing images and colours as soon as it will be possible.

[obiot]

@codename- between pages if possible, like having a search field on the "homepage" that would allow to search the whole documentation.

and for the palette yes, same for the logos

[setthase]

So maybe we should leave white background and use colourful logo? Or you prefer white logo?

Regarding searching... I think this will not be possible without some server behind.

[obiot]

no problem for the search, it was anyway just only if offered by the template (i imagined it would not be)

for the logo, I really would prefer to have the navigation bar in green, and then the logo in white :)

[obiot]

@codename- any update ? :p:p:p

[setthase]

@obiot - unfortunately not yet... I've got really busy times at work (deadline on my neck), but I'll try make all this things on incoming weekend. Sorry, for delay :(

[setthase]

Changes made:

• add missing images
• make header green
• add melonJS logo (I've made it by my own, replace it if you got original in this colours)
• remove unnecessary information from right navigation
• change top dropdown menu to be more condensed
• change order in top nav to be similar to previous one

What else?

[setthase]

@agmcleod - would you be so nice and update deployed version for everybody? 😉

[agmcleod]

Done! http://projects.agmprojects.com/melonjs-docs-template/

Apologies for the delay on uploading that. Took the night off from techy stuff :)

[obiot]

i like it on my side, including what you did with the logo ;)

i'm merging this, we can anyway further update if required directly on master.

[obiot]

I forgot, thank you very much @codename- !