Tiny Thor (made with Monkey X)
Develop on Windows or OSX and deploy easily
Crypt of the Necrodancer (made with Monkey X)
New Star Soccer - BAFTA Winner 2013!!! (made with Monkey X )
Ted - The code editor of Cerberus X
Avalon Legends (made with Monkey X)
Race Time (made with Monkey X)

My Go on the Cerberus X Documentation

Holzchopf Oct 23, 2018

  1. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    Thank you all! =) Does anyone have by any chance a 3rd party framework which's "3rd party documentation" works out-of-the-box with the current makedocs? I've tried Playniax' IgnitionX - does not work =(
     
  2. Phil7

    Phil7 Active Member

    Messages:
    143
    Likes Received:
    36
    Trophy Points:
    28
    I am using IgnitionX and the docs worked fine with older versions of monkey.
    I was really missing the docs a bit because there were some aspects explained, I didn't find in the bananas examples.
     
  3. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    Thanks I'll look into that. It's odd how every subfolder of the IgnitionX documentation has a ".data" suffix :confused:
     
  4. Pierrou

    Pierrou Member

    Messages:
    65
    Likes Received:
    25
    Trophy Points:
    18
    No problem here with IgnitionX and Pyro docs.
     
  5. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
  6. MikeHart

    MikeHart Administrator Staff Member Administrator Moderator

    Messages:
    1,237
    Likes Received:
    300
    Trophy Points:
    83
    Where did you find this?

    EDIT: Found it :)
     
  7. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    MikeHart likes this.
  8. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    I've looked into the 3rd party stuff and... it's not looking good :( It seems to me that at some point the structure how documentation should be organized changed and 3rd party docs still using an "ancient" form. And I ran into some conflicts.

    Some examples:
    1. In pyro/3rdparty.monkeydoc/Pyro.monkeydoc there are links to "Pyro support", "Pyro credits" etc although there are no files "Pyro support.monkeydoc" or "Pyro credits.monkeydoc" in that folder. However, those files are in a sub-folder called "Pyro". So apparently the link resolver used to look in sub-folders with the same name as the file the link is in first.
    2. Many of the 3rd party doc folders have the suffix ".data" even if they contain .monkeydocs instead of data. So to decide whether the folder should be copied (a.k.a. treated like a .data folder) or docced (a.k.a. treated like NOT a .data folder), the folder contents would have to be taken into account.
    3. The structure of 3rd party doc .data folders used to be flattened - e.g. "ignitionx\3rdparty.monkeydoc\Ignitionx\Ignition quick reference guide.data" becomes "data\ignition quick reference guide" in the html target, whereas its sub-folder "ignitionx\3rdparty.monkeydoc\Ignitionx\Ignition quick reference guide.data\Ignition X animate a layer sprite.data" becomes "data\Ignition X animate a layer sprite". I see two problems with that: First, the deeper a folder sits in the structure, the more often it's copied (because - you know - every .data folder is copied with its contents). Second, if two 3rd party docs have a .data folder with a common name, one will overwrite the other.
    The first two issues could probably be solved with a switch that tells the doccer if it's in a .monkeydoc dir or not and have it act different according to the switch. But the third... If I fix it, it breaks a lot of links as there are a lot of "absolute" links in those monkeydocs. If I don't fix it, then, well, I described the problems I see in this above.
     
  9. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    The only reason I could think of, why the folder structure is flattened out, is to reduce the total file path length. Because if I have a 3rd party documentation sitting at T:\modules\myscope\3rdparty.monkeydoc and the doccer copies its contents to C:\Software\Cerberus\docs\html the path and all subjacent paths get extended by -7 characte... wait that's not right ò_Ó

    OK: The only reason I could have thought of was just obliterated. I have no idea why this was done. I am SO against doing this - why should a perfectly fine folder structure an author elaborated with much blood, sweat and tears be torn apart by a stupid tool? Also, didn't this make writing links in your .monkeydocs extremely hard when you had to keep in mind that you must not point to the file where it would be according to you but instead where it will be after a tool has finished doing its copy-magic?

    How many documented 3rd party frameworks are out there? Is it just Ignition X and Pyro? Because yet those two are documented very differently and it seems to me, the way 3rd party docs should be written and organized was never clearly documented and instead, if you wanted to provide a 3rd party doc, you had to trial-and-error your way to an acceptable result. Maybe the "3rd party doccer" just never worked perfectly and instead people had to workaround the doccers capabilities. Is anyone from back then still here? Can someone confirm? Am I overlooking something?
     
  10. MikeHart

    MikeHart Administrator Staff Member Administrator Moderator

    Messages:
    1,237
    Likes Received:
    300
    Trophy Points:
    83
    I never knew how to use the 3rdparty stuff because of the lack of information, so I documented the fantom frameworks in the "normal" way. To create all the cerberusdoc files, I use a self written tool so I can create the descriptions inside the source code. this way a new function /method was still listed no matter if I added a description or not.
    When I digged into the 3rdparty.cerberusdoc feature before, I discovered that it didn't work like it should and found no easy solution to fix it.
     
  11. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    Thanks for confirming my fears. I thought this might be the case, but I was also worried I simply misunderstood how it's supposed to work.

    This means it would probably be somewhere between "not completely catastrophic" and "good" to grasp the opportunity and nail it now. Even if this might mess with some existing 3rd party docs (namely the absolute links to the examples, as far as I can tell right now. 63 of them in Ignition X and 43 in Pyro. All other links seem to be relative and should not be affected). I'm trying some approaches and either we can discuss them afterwards or all but one work and no discussion will be necessary. Plus, I contacted Playniax, maybe he remembers what references he had for writing the 3rd party documentation of his frameworks.
     
  12. Holzchopf

    Holzchopf Moderator Staff Member Moderator CX Code Contributor 3rd Party Module Dev

    Messages:
    263
    Likes Received:
    117
    Trophy Points:
    43
    Mixed news, everyone!

    So far my makedocs-version ignores .monkeydoc files when doccing documents (e.g. when running the 3rd party doccer). I could implement this piece of backwards compatibility quite easily. TBH it's actually already in the code but deactivated as it caused trouble at some place during debugging. If it's going to continue causing trouble, renaming .monkeydoc to .cerberusdoc files will be the way to go.** The bigger issue comes with .data directories:
    • not-real-data-directories (those ending in .data but containing .monkeydoc/.cerberusdoc files to parse) would have to be renamed
    • real-data-directories (those ending in .data an containing images, examples etc) can stay the way they are, but the links pointing to this data might be broken, as the structure in html/data changed
    • mixed-data-directories will have to be copied and the actual data remain in the .data one and the rest in the one that loses it's .data suffix. Here as well the links may have been broken.
    *

    Basically: Back in a time before CX (I guess) the nature of a directory was determined by its contents rather that its suffix. Now a folder named *.data is strictly treated as data folder (copied to html/data) - otherwise it's strictly treated as a folder to run the doccer in. This will prevent .monkeydoc files being copied to html/data needlessly and .data directories being copied over and over to html/data as their structure goes deeper and deeper.

    And as stated above, the .monkeydoc files themselves are no big issue.



    *) If this does not sound super intuitive to you: don't worry, I'm going to make the makedocs help page clear about that.

    Edit
    **
    ) Ok .monkeydoc and 3rdparty.monkeydoc backwards compatibility is back in.
     
    Last edited: Dec 11, 2018 at 3:13 PM
    Phil7 and MikeHart like this.