My Go on the Cerberus X Documentation

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
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 =(
 

Phil7

Administrator
CX Code Contributor
3rd Party Tool Dev
Joined
Jun 26, 2017
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.
 

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
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.
 

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
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?
 

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
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?
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.
 

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
I never knew how to use the 3rdparty stuff because of the lack of information
I discovered that it didn't work like it should
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.
 

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
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:

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
TZMEEE AGAIN! The current makedocs documentation says
In addition, you can add example programs in Cerberus X source code form to an 'examples' directory located in the same directory as the .cxs or .cerberusdoc file the docs are located in.

Such example programs should have the same name as the declaration they are providing an example for, with an '_example' suffix. For example, example code for the above function would be named 'Frobozz_example.cxs'.
However, I've nowhere seen this feature being used, therefore I don't know exactly how it's supposed to work (should that _example.cxs simply be copied to docs/html/examples and is it then linked in the doc page?). And maybe that's also the reason I can't get it to work with the existing Makedocs tool. Has it ever been implemented? Did anyone ever use it? Because if not, I consider not implementing it: There's already a perfectly fine way to provide samples for your documentation (two, if you consider it's also possible putting .cxs files in the .data directory and then linking to them using a relative file system path).
 

MikeHart

Administrator
Joined
Jun 19, 2017
Location
Germany
Has it ever been implemented? Did anyone ever use it?
Don't remove it!
Example: In the cerberusdoc file there is a function/method GetDefaultLanguage.

You need to place a source file called GetDefaultLanguage_example.cxs inside a examples folder in the same folder where the cerberusdoc file is located.

It then automatically ads the source code to the created html file:

upload_2018-12-17_19-28-9.png
 
Last edited:

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
Thanks Mike. I tried it with a method in one of my own modules where it didn't work. Must have made a typo somewhere. Or I could of course look into the old makedocs source and analyse that. But it's good to know already it did work and - even better - the way I imagined. I'll keep it in then ;-)

Edit
I got it to work with the old makedocs. Now it's time to copy that feature =)
 
Last edited:

Holzchopf

Moderator
3rd Party Module Dev
Joined
Jul 31, 2017
Location
Bern, Switzerland
This "examples" feature is back in.

@MikeHart I need your advice once more. The decls.txt seems to be of the format "decl;url;<somethingelse>" - can you explain what that third part is used for in TED? It seems to me it sometimes contains the location of the actual declaration within the source. But I haven't found out under which circumstances this field is written to the decls.txt. So I'm hoping knowing under which circumstances TED looks for that will give me a clue
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
@Holzchopf would you like to be notified of any errors in the docs? I've spotted one or two so far...
 

Paul59

Active Member
CX Code Contributor
Joined
Dec 13, 2018
Location
UK
For example. in Functions->Rnd(3):

Code:
Print Rnd(5,10)         ' anything between 5.0 and 1.0
 
Top Bottom