Quick Links: Download Gideros Studio | Gideros Documentation | Gideros community chat | DONATE
How to document new API in gideros repo ? — Gideros Forum

How to document new API in gideros repo ?

hgy29hgy29 Maintainer
edited March 2015 in General questions
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 ?

Likes: jdbc

+1 -1 (+1 / -0 )Share on Facebook

Comments

  • Maybe send in some information to @ar2rsawseen and he can update the website once he does the merge?
    Coder, video game industry veteran (since the '80s, ❤'s assembler), arrested - never convicted hacker (in the '90s), dad of five, he/him (if that even matters!).
    https://deluxepixel.com
  • Can't wait for 3D support btw, should be great. :)
    Coder, video game industry veteran (since the '80s, ❤'s assembler), arrested - never convicted hacker (in the '90s), dad of five, he/him (if that even matters!).
    https://deluxepixel.com
  • ar2rsawseenar2rsawseen Maintainer
    Accepted Answer
    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
  • hgy29hgy29 Maintainer
    Understood ;) Why not using something like doxygen and annotating API directly in the source code ?
  • ar2rsawseenar2rsawseen Maintainer
    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

    Likes: gdillon

    +1 -1 (+1 / -0 )Share on Facebook
  • @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.
    Coder, video game industry veteran (since the '80s, ❤'s assembler), arrested - never convicted hacker (in the '90s), dad of five, he/him (if that even matters!).
    https://deluxepixel.com
  • 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
  • gorkemgorkem Maintainer
    edited March 2015
    @gdillon good to see you here too :) I also thought (seen somewhere?) that you are working on 3rd level menus, am I right?
  • 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!
  • ar2rsawseenar2rsawseen Maintainer
    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
  • 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
  • hgy29hgy29 Maintainer
    @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 ?
  • ar2rsawseenar2rsawseen Maintainer
    @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?

  • hgy29hgy29 Maintainer
    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...
  • ar2rsawseenar2rsawseen Maintainer
    Here is an SQL dump from docs db:

    zip
    zip
    docs.zip
    101K
  • 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!
  • hgy29hgy29 Maintainer
    @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.
    zip
    zip
    Sprite.zip
    5K
    +1 -1 (+3 / -0 )Share on Facebook
  • That seems like a good idea.
    Coder, video game industry veteran (since the '80s, ❤'s assembler), arrested - never convicted hacker (in the '90s), dad of five, he/him (if that even matters!).
    https://deluxepixel.com
Sign In or Register to comment.