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

    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

    • SinisterSoftSinisterSoft Maintainer
      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
      +1 -1Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      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
      +1 -1Share on Facebook
    • 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
      http://appcodingeasy.com/Gideros-Mobile
      +1 -1Share on Facebook
    • hgy29hgy29 Maintainer
      Understood ;) Why not using something like doxygen and annotating API directly in the source code ?
      +1 -1Share on Facebook
    • 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

      http://appcodingeasy.com/Gideros-Mobile
      +1 -1 (+1 / -0 )Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      @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
      +1 -1Share on Facebook
    • gdillongdillon Member
      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
      +1 -1Share on Facebook
    • 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?
      +1 -1Share on Facebook
    • gdillongdillon Member
      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!
      +1 -1Share on Facebook
    • 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
      http://appcodingeasy.com/Gideros-Mobile
      +1 -1Share on Facebook
    • gdillongdillon Member
      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
      +1 -1Share on Facebook
    • 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 ?
      +1 -1Share on Facebook
    • 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?

      http://appcodingeasy.com/Gideros-Mobile
      +1 -1Share on Facebook
    • 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...
      +1 -1Share on Facebook
    • ar2rsawseenar2rsawseen Maintainer
      Here is an SQL dump from docs db:

      zip
      zip
      docs.zip
      101K
      http://appcodingeasy.com/Gideros-Mobile
      +1 -1Share on Facebook
    • gdillongdillon Member
      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!
      +1 -1Share on Facebook
    • 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

      Likes: SinisterSoft, bali001, Eshan

      +1 -1 (+3 / -0 )Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      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
      +1 -1Share on Facebook
    Sign In or Register to comment.