How to document new API in gideros repo ?

hgy29

Hi, I am almost finished in implementing 3D support (still need to test on iOS/MacOS so far but thats not the point). Now I'd like to add my enhancements into the gideros reference manual, but so far I've only found a reference_manual.html file, and I guess it must have been generated by an appropriate tool. Or not ???

What is the regular process to document new API calls ?

SinisterSoft

Maybe send in some information to @ar2rsawseen and he can update the website once he does the merge?

SinisterSoft

Can't wait for 3D support btw, should be great.

ar2rsawseen

Thats a great question

We were looking for a platform to community managed docs, but did not find the one that would fit us yet

hgy29

Understood Why not using something like doxygen and annotating API directly in the source code ?

ar2rsawseen

probably because it is too time consuming to transfer back to it now

Similarly there was an interesting paltform like http://readme.io/ which is almost what we would want, except there is no collapsible third level menu and you cant import docs in any format

Currently docs are in mysql db, so could be exported in any needed format

SinisterSoft

@ar2rsawseen You need a flag in the gideros user account database to allow access to another webpage that shows a form to edit/add to the docs.

gdillon

Hey guys, sorry to be creepy but I'm a founder of ReadMe.io and wanted to chime in. It's true, we can't import yet, but we can automatically sync API reference docs from a GitHub repo, and there's the "suggest edits" feature that enables wiki style editing for your developer community. Feel free to reach out to me at support <<at>> readme.io if you have any questions. /stalker

gorkem

@gdillon good to see you here too I also thought (seen somewhere?) that you are working on 3rd level menus, am I right?

gdillon

Yes, @gorkem! We have a new template currently in testing with a few select partners. There's the extra level of subcategorization, as well multiple documentation sections. I.e., if you have an SDK and an API, but don't want them to share the same navigational structure, you'll be able to toggle between them. It's a bit of a 2.0 release of the front end of ReadMe. Thanks for your interest!

ar2rsawseen

I think we could probably live without import and copy pasting the docs, but collapsible 3rd level would really help to make docs more easier to navigate

gdillon

Thanks for the feedback, @ar2rsawseen. When we first launched ReadMe, we anticipated folks documenting an API and how to use an API only. We never anticipated the amount of guide and tutorial content people are adding to their docs (which, of course, actually makes for an immensely better onboarding and learning experience for your developers). Subcategorization and multiple documentation sections will provide a lot more breathing room for larger projects. We're targeting a slightly broader beta release in just a week or two. Shoot me a note if you're interested! ~g

hgy29

@ar2rsawseen, @gdillon, if we can't import the docs in readme, perhaps we can write an import/export tool from mysql to readme github format ?

ar2rsawseen

@gdillon it is because, there is no such platform for simple docs.

Wiki is ok, but organizing menu there is a nightmare

Currently we have something like this:

http://docs.giderosmobile.com/reference/

@hgy29 but again will the imported docs be organized by the menus?

hgy29

Well, IMHO docs should really be kept along source code in some way, i.e. inside gideros repository. I think that it would be convenient to manage it as tagged text files, say one file per class/topic ideally. The files format could be defined along requirements of the current sql storage, and an import export tool could then be created.
This way, docs could be kept in the repo and transferred easily in the sql database, and current tools to export it as html reused as well.

@ar2rsawseen, if can give me the sql storage structure, I will try to come up with something...

ar2rsawseen

Here is an SQL dump from docs db:

gdillon

Hey @ar2rsawseen and @hgy29! You can read more about how we automatically generate API reference docs here:

http /readme-sync.readme.io/v1.0/docs

We think these sorts of tech-heavy docs (as opposed to tutorials or topical guides) should definitely be kept as close to the source code as possible. However, we're making a conscious decision (for now) to not simply replicate the GitHub documentation feature. I know that's a little inconvenient, but we think we have something that is much more powerful than just syncing git markdown docs.

Your current docs look fine. Our new template should be able to accommodate the amount of content and organization very well, especially since you have two APIs. And, since you guys seem to have an awesome developer community here, there might be some real value in collaborative editing and a support section. Let me know how I can help you out!

hgy29

@ar2rsawseen, what would think about a git hosted doc folder that would hold one xml file for each object in the database ? I've made an export tool that generate files like the attached one, and I should be able to make an update tool that would check the files and update the database accordingly the other way.

SinisterSoft

That seems like a good idea.