expirimenting with documentation refactor

[mreinstein]

I'm interested in working on some of the pixi.js documentation, especially with v3 on the way. I've put together a very simplistic skeleton for how docs could look. http://mreinstein.github.io/pixijs-docs

prototype goals:

• consolidate examples, API docs, and tutorials into one place
• adopt a clean, simple visual interface
• provide a place where examples are not just code but include line-by-line descriptions to gently ease people into features

I've basically taken the doc code from three.js and adapted it for pixi, since I think it's a really elegant starting point, and it's MIT licensed.

I'd like to get feedback from some people before I invest much more time in this. If this is something that we like, I'm happy to keep working on it. :)

What's done:

• the basic example has been added, with descriptions on what each line is doing.
• the skeleton framework for linking pages into table of contents, searching, pretty printing,etc.

What's not done:

• None of the links to examples are populated
• none of the API reference docs are tied in to actual docs yet
• running examples should be embedded at the bottom of each one.

[englercj]

Is this actually a jsdoc theme, or did you do this staticly? We generate the docs from jsdoc, sow e don't want to stop doing that.

[mreinstein]

Is this actually a jsdoc theme, or did you do this staticly?

I haven't linked any of the API docs into this. The focus of the exercise was coming up with a site structure that unifies tutorials/examples which are written more like articles, with API docs which would be auto generated.

We generate the docs from jsdoc, so we don't want to stop doing that.

Yeah I'm not suggesting we should statically maintain docs. If we went with this structure, I think it would make sense to keep using jsdoc syntax, and produce API docs as sub pages of this. I think it's just a matter of coming up with a different theme/output.

[GoodBoyDigital]

Hi @mreinstein ! First off thanks for taking the time to start looking at the docs / presentation. We are often very busy on making pixi itself and often find that this stuff tends to get pushed to the back of the queue.

Good docs / tutorials is key to helping out new users get the best out of our little renderer so someone like yourself offering to help us out and help create awesome docs and detailed tutorials is most welcome :+1:

As @englercj (and yourself) suggested keeping the docs generated of the back of the jsdocs is definitely the best way to go. We have started work on an examples page that lets people live edit our examples which can be found here:

http://pixijs.github.io/examples/view.html?s=basics&f=basic.js&title=Basics

The idea is that we would like to create a collection of little examples that focus on one feature at a time. The examples we currently have are ok but often do multiple things at once. Im am quite keen on the way @photonstorm has created lots of smaller but focused examples here: https://phaser.io/examples.

I also LOVE the idea of also having a few tutorials that are written more like articles (as you have done) A few of those exploring core pixi concepts would be very handy for new users. We could also have a few more advanced ones where I can explain some of the best ways to use pixi efficiently.

Presentation wise the three.js inspired look is certainly clean and easy to navigate which is rad. I guess the challenge here is can we get the docs auto generated into this style?

The main reason this stuff does not exist is that is all takes time to create and for me (and @englercj) we tend to pour any time we have into the engine itself. If your up for helping us out it would be most welcome and i'm sure the community will be very appreciative also :)

[mreinstein]

We are often very busy on making pixi itself and often find that this stuff tends to get pushed

I know, I look at the repository activity on pixi's dev branch daily. You people are crazy busy cranking out changes! :)

someone like yourself offering to help us out and help create awesome docs and detailed tutorials is most welcome

I'm in a good position to help with that because I lack the internal implementors knowledge that you folks have. I can provide perspective on what a newbie needs most since I am one. :) I've monopolized people's time in github issues asking basic questions and I'd love to give something back by building up some stored knowledge on how to go about doing things.

We started work on an examples page that lets people live edit our examples

They look nice! In my opinion, as a newbie, the ability to live edit code is less important than having a gentle line-by-line guide for the key bits. I'd gladly sacrifice the live edit capability for less noise and a gentler intro with more hand holding in the right places.

The idea is that we would like to create a collection of little examples that focus on one feature at a time. The examples we currently have are ok but often do multiple things at once.

I really love the idea of small examples that focus on one feature at a time too. It seems that in every pixi.js example, there are roughly 5-10 lines that really "matter". Isolating and explaining those bits might reduce the signal-to-noise ratio.

the challenge here is can we get the docs auto generated into this style?

Yeah I think that's the biggest challenge (at the moment anyway.) I tentatively have a plan to read up on the plugin authoring documentation for jsdoc (http://usejsdoc.org/about-plugins.html) and produce one that spits out formatted html.

Something that might be controversial/worth discussing: It might be worth having a much simpler output from the jsdoc input. For example, three.js's docs basically just show public methods and properties. the protected/private stuff isn't very useful for a newbie or someone that isn't implementing pixi.js internals. Given that I'm presenting a user-centric documentation view, is it cool if I do something similar with our docs?

it all takes time to create and for me (and @englercj) we tend to pour any time we have into the engine itself

yep, I totally get that. I think that's the best use of your time as there is a ton to do on the engine itself. :)

[KtorZ]

Hey guys :) I totally support you @mreinstein ! I've just started using PIXI.js two weeks ago; Glad to see that I've choosen the right moment, just after the v3 was released. However.. PIXI.js documentation is quiet awful and now.. most of existing examples are either deprecated or irrelevant. Even in the doc accessible on github ( http://pixijs.github.io/docs/) there are a lot of deadlinks (in fact, the namespace's reference PIXI is missing for a lot of classes), and the layout is catastrophic in a split window. So, i'm keeping a close eye to your work. I wish I could help a bit, nevertheless, I think that I need to get more insight about PIXI first.

Even if the message sounds a bit like a complain, you're doing an awesome work guys ! So, give us a bit of help to be able to use your engine at 100% of its capacity ! :D !

[mreinstein]

@KtorZ where I left off is looking at jsdoc's plugin API and coming up with a small tool/template that generates nicer looking docs http://usejsdoc.org/about-plugins.html

I haven't gotten around to this yet because I started a new contracting gig but it's definitely something I plan to tackle sometime this month. If you want to help, digging in on that would be a great start!