docs: Make index page for each method

[AaronAcerboni]

The index page should list all the methods in catagories possibly ordered by most commonly used.

For each method its signature could be displayed as well as a brief description of what it does.

Each method name could link to its respected method page were a full description is displayed as well as examples.

In gh-pages branch, copy /api/index.html into /api/append/index.html etc Change {% assign category = site.categories.api %} to {% assign category = site.categories.append %}

Then in the /docs folder, any files that have in the frontmatter category: append will be used to build the append method page. We could use this for documenting all the different types of method signature. E.g. in the /docs folder, there might be a md file for append(elements), another one for append(elements, attr), etc.

[premasagar]

All changes to be in the /docs folder, making a new branch off master.

[AaronAcerboni]

https://gist.github.com/anonymous/a3485bb87baf744d3f7c

Index.md and buildApiDocs

[AaronAcerboni]

I followed the instructions described in the first post but the specific method page for append isn't fully rendered.

This is because the url paths to the css and javascript are incorrect.

localhost:4000/api/append

[AaronAcerboni]

(Copying over from email)

You could also have multiple doc files for each method signature variant of that certain method. Doing this would allow for more links in a method page's sidebar. The only problem I see with this is the method signature name as a file name.

[AaronAcerboni]

On the api index page, if we want each method to be available on the side bar we will need an additional md file for each method.

This would mean a md file for the short description (category api) and possibly one for each variant of the method signature (category methodName).

Does this sound right?

[premasagar]

Ok, so it looks like the paths to those assets need to be made relative to the root domain e.g. /css/ rather than relative, e.g. ../css/

Yes, unfortunately this will mean lots of bitty .md files. Ideally we should change Satya to prevent this, but in the short term we will need to do that.

The filename should include only lowercase alphanumerics, plus -. If the section title needs other characters then add a title param in the frontmatter (see the "Symbols & Templates" page).

Premasagar Rose, Dharmafly http://dharmafly.com dharmafly.com / 07941 192398 premasagar.com twitter.com/premasagar L4RP.com asyncjs.com

[AaronAcerboni]

Ok, so it looks like the paths to those assets need to be made relative to the root domain e.g. /css/ rather than relative, e.g. ../css/

Should this be approached only to Pablo's instance of gh-pages or satya?

[premasagar]

Satya. We should keep effort on the main site architecture there.

Premasagar Rose, Dharmafly http://dharmafly.com dharmafly.com / 07941 192398 premasagar.com twitter.com/premasagar L4RP.com asyncjs.com

[AaronAcerboni]

I've changed it over on Satya to use the root reference.

I've also pushed a revised docs in the new apidocs branch. I've kept the old docs since there is probably some information to copy over. I would expect the old docs will be removed eventually. Then apidocs can merge to master and update the public gh-pages.

For the api list page I did not split each method name to their separate md file but kept them in categories (Node positioning, manipulation, properties, iteration, misc, data, events etc...). So there are files for each category. This is so I did not lose the category headings and the sidebar would not gain a scrollbar from all of the method names.

If you want to see what it looks run satya build from the apidocs branch, switch over to gh-pages and run satya server.

What still needs to be done is a markdown page describing each method (of category: methodName) and a markdown file for each signature. I think for the filenames its best to name it something like:

24. Append.md 25. Append2.md 26. Append3.md

With the front matter title being used.

Assuming append had multiple signatures.

In addition the respected api/methodName/index.html template needs to be made for each method on the gh-pages branch.