Quick Links: Download Gideros Studio | Gideros Documentation | Gideros community chat | DONATE
Fixing broken links in Wiki (Articles Tutorials) - Page 2 — Gideros Forum
  • Home
    • ›

    Fixing broken links in Wiki (Articles Tutorials)

    24567

    Comments

    • SinisterSoftSinisterSoft Maintainer
      edited November 2019
      I personally think add the robots.txt so it will fade away, possibly put a banner on the top to the new docs. The file will have to not block robots from the main site - just the old docs.

      Ideally, then we need to make it so the new docs are just as easy to use as the old docs.

      If anyone can pinpoint what it is that is missing or what would fix it (so you then prefer the new over the old) then please let us know. :)

      The new docs have the major advantage that anyone here can update them, add examples, etc (as long as they have been added) rather than all the work given to just one or two people.
      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
    • olegoleg Member
      SinisterSoft said:

      I personally think add the robots.txt so it will fade away, possibly put a banner on the top to the new docs. The file will have to not block robots from the main site - just the old docs.

      Ideally, then we need to make it so the new docs are just as easy to use as the old docs.

      If anyone can pinpoint what it is that is missing or what would fix it (so you then prefer the new over the old) then please let us know. :)

      The new docs have the major advantage that anyone here can update them, add examples, etc (as long as they have been added) rather than all the work given to just one or two people.


      I think you need to set another style for giderospedia. But this is not critical.
      my games:
      https://play.google.com/store/apps/developer?id=razorback456
      мій блог по гідерос https://simartinfo.blogspot.com
      Слава Україні!
      +1 -1Share on Facebook
    • antixantix Member
      I think the point being totally overlooked here is that the wiki does not present the basic API information in an easy to use manner. Let's look at a use case...

      A new user wants to know about Sprites. They click the "Main API" link, then click the Sprite" link. After reading a little bit about Sprites the user then decides they want to read about Bitmaps. They have to click the "back" button in their browser, and then click on the "Bitmap" link. That's just insane!

      In my opinion, the old API Reference is far easier to use than the wiki, but of course now the documentation on the main site is lacking behind the wiki.

      So how would one now go about printing the API Reference? Are the documents on the GitHub repository now also obsolete?

      Personally I feel the documentation should always be downloadable in either XML or JSON formats so that they can be interpreted in whatever way the downloader desires. Agree or disagree?
      +1 -1Share on Facebook
    • plicatibuplicatibu Member
      My 2 cents: I think wikis in general are horrible to use. I really dislike them.

      That said, I would keep it to put articles and tutorials (changing it to another thing would require too much effort that I think it would be better employed improving Gideros).

      API docs I would link to another subdomain, say api.giderosmobile.com and to ease developers live, its content would be automatically generated from source code (I'm assuming maintainers use doxygen or a similar tool to generate Ap
      API documents).

      I would neither remove old docs nor block robots from indexing them because it will penalize Gideros' site.

      Imagine how many people may miss the chance to know about Gideros just because Google removed many pages from its searching engine result... Gideros cannot lose any chance to acquire new users (as no framework can).

      For older docs I'd put a bright and blinking red message saying these docs are outdated and ask users to click to new documentation.

      Regards.

      Likes: MoKaLux, antix, oleg, hgy29, SinisterSoft

      +1 -1 (+5 / -0 )Share on Facebook
    • antixantix Member
      The problem with having "old" and "new" docs is that you have fragmentation. It doesn't make sense to have old documents with flashing red text pointing to the new documents, especially when the new documents are hosted in such an unfriendly manner.

      It's kid of tricky to be sure.

      I'd be keen to know how the docs are generated also.
      +1 -1Share on Facebook
    • hgy29hgy29 Maintainer
      antix said:


      I'd be keen to know how the docs are generated also.

      They are not, and that’s the main issue here. I proposed to switch to a doxygen annotation style several years ago, but it didn’t receive much approbation at that time.
      +1 -1Share on Facebook
    • plicatibuplicatibu Member
      edited December 2019
      @hgy29 It's a pitty.

      If the source code had comments in doxygen style, it would be a breeze to generate a beautiful, easy to navigate API site without any effort on your side.

      Likes: hgy29

      +1 -1 (+1 / -0 )Share on Facebook
    • MoKaLuxMoKaLux Member
      I see a problem with doxygen though: the one who writes the code would also write the docs?!
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • hgy29hgy29 Maintainer
      It is far much easier to write the docs along the code than to switch to another tool to insert the doc. On the wiki, you have to create a page per function, which is tedious.

      Likes: plicatibu

      +1 -1 (+1 / -0 )Share on Facebook
    • hgy29hgy29 Maintainer
      Some kind of both forward and reverse annotation process would be great
      +1 -1Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      edited December 2019
      @hgy29 I think we should use what solution you recommend. If you say it's easier to write API docs in doxygen then that's what we should do.

      Then once they are up to date we change the link in the wiki to point there.

      (then using the wiki for regular instructions and 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
    • keszeghkeszegh Member
      i'd also be happy if there would be a reference that has the functionality of the old one (and is easy to maintain). mainly i need a pane with all the functions to switch quickly between them.
      Longtitle Productions, creator of
      Fragmenter - animated loop machine and IKONOMIKON - the memory game
      +1 -1Share on Facebook
    • hgy29hgy29 Maintainer
      Doxygen isn’t a complete solution, docs have to be generated from annotations in the source code into html by doxygen and there is no room for examples. Wiki is better in that respect.
      My current thoughts would be:
      - keep the wiki for doc content but tag use tags inside it so that we can use tools to index it ( it is already the case)
      - Annotate code with method name, signature and short description (doxygen/java like)
      - Make a script to keep both in sync
      - Make another script/php page to present the api docs in a better way (thanks to the gathered indexes)

      Likes: SinisterSoft

      +1 -1 (+1 / -0 )Share on Facebook
    • MoKaLuxMoKaLux Member
      edited December 2019
      imho we should stick with the wiki because it is easy to add articles to it and we can all participate.
      I understand that people find it hard to navigate?
      And it is also hard to add a new page for every functions.

      When you look at the wiki it seems that some pages have only one or two lines in them!

      Can I suggest a few things to help?
      1- put all on the main page and clean it a bit, for example:


      2- put all the methods/functions on the same page as well? That is Desciption Example Methods Events Constants...



      I can do it (?) step by step if you all agree.
      new_wiki_homepage.png
      955 x 814 - 31K
      new_wiki_accelerometer.png
      523 x 800 - 31K

      Likes: Apollo14

      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1 (+1 / -0 )Share on Facebook
    • keszeghkeszegh Member
      edited December 2019
      i'd like to have a side menu. like here: https://docs.blender.org/manual/en/latest/index.html
      cannot we maintain the mkdocs in github? then everybody could edit it.
      i started to write the manual for my app in mkdocs and i could work with it quite fast and it has the side menus that i like:
      https://longtitleproductions.bitbucket.io/fragmenter/usermanual/

      or would that mean that we have to copy everything to mkdocs manually and it's too big task for us? is there any other disadvantage?
      Longtitle Productions, creator of
      Fragmenter - animated loop machine and IKONOMIKON - the memory game
      +1 -1Share on Facebook
    • MoKaLuxMoKaLux Member
      edited December 2019
      @keszegh I don't like the blender docs it looks too clumsy when you navigate through the sections. I believe they use this site https://docs.readthedocs.io/en/stable/index.html (it seems to be the new kid on the block)
      One advantage is it can export to pdf but overall imho it doesn't seem to be a good choice for gideros docs?

      On the other hand you have mkdocs which looks much more a good fit for gideros but the problem is how will we (the community) update it? If done through github we would need our commit to be pushed (or the other way around?) to see the results. Same for readthedocs.io.
      @keszegh I have to admit that your user manual looks great.

      Let's face it guys I don't think we are going to change from mediawiki? and imho it is a very good choice sinistersoft did. The only thing missing is the damn left side menu!
      So how can we make wikimedia more confortable to us all?

      Likes: hgy29

      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1 (+1 / -0 )Share on Facebook
    • MoKaLuxMoKaLux Member
      edited December 2019
      I am going to make a few changes to gideros wiki, hope you have a backup :)
      Plus I am sure one could make a gideros app to put the wiki into a single doc (html, txt, pdf).
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • keszeghkeszegh Member
      thanks for the comments and compliments @MoKaLux .
      i agree that if we can add a side-menu to the wiki then i'd happy enough.
      Longtitle Productions, creator of
      Fragmenter - animated loop machine and IKONOMIKON - the memory game
      +1 -1Share on Facebook
    • hgy29hgy29 Maintainer
      @MoKaLux is right, mediawiki was choosen because it allows anyone to edit the doc online, and this was a good move for a small community like us. But someone could write a script or php page to present the docs from the wiki into something more easy to browse.

      I don’t think we need to rewrite everything, just to present them differently.
      +1 -1Share on Facebook
    • keszeghkeszegh Member
      the right side sidebar is nice here:
      https://tiddlywiki.com/

      i don't know if it relates to our wiki or not.
      Longtitle Productions, creator of
      Fragmenter - animated loop machine and IKONOMIKON - the memory game
      +1 -1Share on Facebook
    • MoKaLuxMoKaLux Member
      keszegh said:

      thanks for the comments and compliments @MoKaLux .
      i agree that if we can add a side-menu to the wiki then i'd happy enough.

      @keszegh you're welcome :)
      + from the mediawiki:
      The sidebar is displayed on the left edge of the page below the site logo (if using the MonoBook or Vector skin). This sidebar gives you access to important pages in the wiki such as Recent Changes or Upload File.
      I am afraid we cannot use their side bar unless we install an extension but I have looked and none seem to fit or are very outdated :/
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      An extension could possibly be adapted or created to do what we want I think. I'm thinking maybe we could make a tag that presents the information scanned from a database. Then the examples can be placed underneath the 'tag' by users AND the API could be updated via scanning the source code?
      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
    • MoKaLuxMoKaLux Member
      edited December 2019
      @SinisterSoft I was wrong.
      The sidebar could be useful to link important pages like the Main API, Plugins and maybe LUA API. https://www.mediawiki.org/wiki/Manual:Interface/Sidebar

      I am afraid I cannot do it because we need special permissions:
      To customize the MediaWiki:Sidebar on a wiki, you need first to be logged in with a user that has the editinterface permission - for administrators this is enabled by default.

      Edit: it looks like we have indeed the sidebar but it is hidden (it's the little arrow near the gideros logo at the top of the page). So its placement depends on the skin:
      The Monobook and Vector skins place the navigation bar on the top-left (top-right for right-to-left languages) along with the search bar and toolbox, but the placement may be different in other skins.

      We may need to choose another skin so we can have the sidebar to the left and add to it anything we want :)
      One thing would still be missing: the sidebar won't follow the page :'(
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • MoKaLuxMoKaLux Member
      we are very close guys!

      Likes: keszegh

      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1 (+1 / -0 )Share on Facebook
    • plicatibuplicatibu Member
      Just a bit of examples for those that have never worked with doxygen.

      Below you have some links whose pages were generated from source code:

      http://llvm.org/doxygen/
      https://developer.gnome.org/gtkmm/stable/hierarchy.html

      Some people use Sphinx to extend the doxygen functionality. Eg: https://www.nltk.org/

      And here a little tutorial on how to integrate Sphinx with doxygen: https://devblogs.microsoft.com/cppblog/clear-functional-c-documentation-with-sphinx-breathe-doxygen-cmake/

      But I think it would be better to stick to wiki (or should I say weak?) for docs and examples and use doxygen for API.

      Regards.


      +1 -1Share on Facebook
    • antixantix Member
      I don't see why this is being made more complicated than it actually is. The fact of the matter is that for an API reference you need a bloody navigation bar.

      What's wrong with this.... http://kapitiindependentnews.net.nz/cliff/reference.html

      This is what I use because I hate the wiki and clicking my mouse a million times just to find some information (it was part of my own badly received attempt at revamping the Gideros website).

      Unfortunately now that the documentation has been moved to the wiki I am unable to keep my own documentation system up to date, because yeah... progress.

      I suppose I could scrape the wiki but when somebody goes and changes those pages then I would have to rewrite my scraper.

      I reiterate... there must be some place where the documentation is stored in a standardized format (XML or JSON) that can be downloaded and used as required.

      Is that really too much to ask?

      Likes: plicatibu

      +1 -1 (+1 / -0 )Share on Facebook
    • MoKaLuxMoKaLux Member
      edited December 2019
      @SinisterSoft I need your help please. In the wiki:
      1- we need to change the default skin so we have the sidebar on the left.
      we can choose between those three already available:




      2- we need to change the sidebar so we can add any links we want. https://wiki.giderosmobile.com/index.php/MediaWiki:Sidebar

      3- I need permissions to do it!

      @antix it seems we can do it in mediawiki
      https://stackoverflow.com/questions/23855496/extract-text-from-mediawiki-xml-dump-without-installation-api?rq=1
      https://www.mediawiki.org/wiki/API:Parsing_wikitext#parse
      https://commons.wikimedia.org/w/api.php?action=query&&titles=Category:London&prop=langlinks&lllimit=500&format=xml&rawcontinue

      I am sure mediawiki can do a lot that we are unaware of!
      It's like gideros :)

      I like the timeless skin the most, what about you let's vote!
      skin_monobook.png
      822 x 447 - 37K
      skin_timeless.png
      1109 x 527 - 39K
      skin_vector.png
      1161 x 447 - 35K
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • SinisterSoftSinisterSoft Maintainer
      I can't change that - I think that adding the sidebar to the existing theme may be better.
      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
    • MoKaLuxMoKaLux Member
      MoKaLux said:

      Edit: it looks like we have indeed the sidebar but it is hidden (it's the little arrow near the gideros logo at the top of the page). So its placement depends on the skin.

      The sidebar is already here but the default skin puts it in a place that is not usable. You just need to change the default skin to one of the above. The skins are already installed.
      Then we can modifiy this https://wiki.giderosmobile.com/index.php/MediaWiki:Sidebar and add all the links we want.

      That seems easy, I don't see the problem changing the default skin.
      my growING GIDEROS github repositories: https://github.com/mokalux?tab=repositories
      +1 -1Share on Facebook
    • antixantix Member
      edited December 2019
      @MoKaLux Thanks for the links but I have absolutely no idea how to use that do extract the information from the Gideros wiki. It really shouldn't be rocket science.

      After messing about for a few minutes I came up with this... https://wiki.giderosmobile.com/api.php?action=parse&page=Application&format=json

      The output is basically the web content shoehorned into a JSON structure. Parsing it to enable it to be actually useful like having some semi-sane navigation functionality looks to be quite tricky.
      +1 -1Share on Facebook
    Sign In or Register to comment.