SRL Archive - MSI Suggestions

I've committed a MSI/Doc folder that contains various documentation files. Wizzup is going to set it up when he has time. I've also updated Antiban.simba with the new documentation comments if you want to check it out.

Keep in mind that once it's setup, Anitban.simba will serve as an example for you guys to see, and we'll vote on whether or not we should keep it; although, I have a feeling we will. ;)

From: Coh3n
Okay guys, click here to see the documentation.

I'm sure you'll all agree to use it, but I just want to make sure before I start changing the script/function headers. Take a look at Antiban.simba to see what the commenting will look like. Yes, it's pretty long, but I think it's neat and it avoids us having to constantly update the Core tutorial (which isn't up to date anyway).

This documentation will be automatically updated depending on our commits. :) If you write a function header, be sure to be very descriptive and explain the parameters. You shouldn't really need it (just follow the format of what I did for Antiban.simba, but if you're wondering how to do different formats you can go here).

For functions with several parameters, I think it will be best to use a list format. I'm not positive of how to do this yet, but as soon as I am I'll post it here.

:)

• Animating.simba
• Antiban.simba
• Banking.simba
• Debug.simba
• Globals.simba
• Items.simba
• Locations.simba
• Mainloop.simba
• Manipulation.simba
• Objects.simba
• Obstacles.simba
• Reports.simba
• Scripts.simba
• Setup.simba
• Skills.simba
• Track.simba
• Walking.simba
• Mining.simba
• Woodcutting.simba
• Magic.simba
• Fishing.simba
• Cooking.simba
• RunMe.simba

Here's a couple templates. You should just have to copy/paste into the include and replace the necessary information.

(*
MSI_FindRandoms
~~~~~~~~~~~~~~~

.. code-block:: pascal

  procedure MSI_FindRandoms;

Checks to see if the player has encountered a random event

.. note::

  | Author: Coh3n
  | Last Updated: 07 December 2010 by Coh3n

Example:

.. code-block:: pascal

  if (not FindObjects) then // Note that FindObjects is used only as an example
    MSI_FindRandoms;
*)

For using lists (functions/procedures with several parameters):

(*
MSI_AddToProggy
~~~~~~~~~~~~~~~

.. code-block:: pascal

  procedure MSI_AddToProggy(WhatToAdd, Obj, Item, Quant: Integer);

Adds variables specified by 'WhatToAdd' to the progress report. If one of the
parameters is unused (i.e. you're adding Loads, set it to -1). See
MSI_CountItems in Banking.simba for a good example of this being used.
    - WhatToAdd: There are different 'PROG_' constants found in Globals.simba.
    - Obj: Represents the index of the object in the player's Script array.
    - Item: Represents the index of the item in the player's Script.Items array.
    - Quant: The quantity you want to add.

.. note::

  | Author: The MSI Team
  | Last Updated: 25 November 2010 by Coh3n

Example:

.. code-block:: pascal

  MSI_AddToProggy(PROG_ADD_EXP, -1, -1, 1000); // To add experience
  MSI_AddToProggy(PROG_ADD_ITEMS, 0, 2, 28);   // To add items
*)

I took the liberty to give myself commit access to MSI. I made a change to the Makefile and the index.rst; it works here.

Example PDF: http://sheeva.villavu.com/merlijn/tmp/MSIDocumentation.pdf

From: Wizzup?
I took the liberty to give myself commit access to MSI. I made a change to the Makefile and the index.rst; it works here.

Example PDF: http://sheeva.villavu.com/merlijn/tmp/MSIDocumentation.pdf

Awesome! :)

Is there any way to change the author to say The MSI Team rather than Cohen Adair? And what about a link like this? And is there a way to put the notes on separate lines? I wanted Author and Last Updated on separate lines.

Thanks a lot, Wizzup! :)

E: How do us SL's update it? Do we just need to update the comments in the files?

From: Wizzup

SRL 5 is (supposed, it's not finished yet) to be a clean up of SRL. A lot has been cleaned up, but I think there is more to be cleaned up. It also implements a new documentation system. See it in action, here: http://wizzup.org/srl5doc/
Converting all our documentation to this new system took me quite awhile. Thanks to Fakawi and Markus for doing some files too. Everything in core/ is documented; or rather, ported to the new documentation system.

The new documentation system is really simple to use. You'll just need to learn Restructured Text. (http://sphinx.pocoo.org/rest.html)
Restructured Text is trivial; it's a lot like text. I don't expect everyone to be flawless in using the new system, but make sure you at least read a part of that guide. There's one last thing to decide on; and that is whether we will keep the example usage for each function or not. Currently, it does look at bit messy if there is no example. (No example but having the example block also prevents the generation of a PDF, it doesn't like empty code-blocks.)

~RM

From: Coh3n
Awesome! :)

Is there any way to change the author to say The MSI Team rather than Cohen Adair? And what about a link like this? And is there a way to put the notes on separate lines? I wanted Author and Last Updated on separate lines.

Thanks a lot, Wizzup! :)

E: How do us SL's update it? Do we just need to update the comments in the files?

Open up conf.py and change:

copyright = u'2010, Cohen Adair'

(And the two other occurrences)

Different notes:

.. note::

  Author: Naum

.. note::

  Last Updated: 07 September 2010 by Coh3n

Not sure if this will also work (probably not):

.. note::

  Author: Naum

  Last Updated: 07 September 2010 by Coh3n

Update it, do you mean the pdf? Anyone with Linux can easily do this, although I think with the make.bat you can at least generate the html. But I could probably set up a system that does this automatically.

From: Wizzup?
Update it, do you mean the pdf? Anyone with Linux can easily do this, although I think with the make.bat you can at least generate the html. But I could probably set up a system that does this automatically.

The PDF and online doc (if you have the link that would be great ;)).

Automatically generating the HTML would be great. I think I have a site I can the HTML can be uploaded to if you don't want to host it.

E: I managed to generate an HTML, except there was nothing in the contents. :o Just kept saying "Unknown file" for all the files in index.rst, which I'm assuming is because I don't have those files, and I can't figure out how to run your py script to get them. :o

Okay guys, click here to see the documentation.

I'm sure you'll all agree to use it, but I just want to make sure before I start changing the script/function headers. Take a look at Antiban.simba to see what the commenting will look like. Yes, it's pretty long, but I think it's neat and it avoids us having to constantly update the Core tutorial (which isn't up to date anyway).

This documentation will be automatically updated depending on our commits. :) If you write a function header, be sure to be very descriptive and explain the parameters. You shouldn't really need it (just follow the format of what I did for Antiban.simba, but if you're wondering how to do different formats you can go here).

For functions with several parameters, I think it will be best to use a list format. I'm not positive of how to do this yet, but as soon as I am I'll post it here.

:)

It's looking great Coh3n! :)

Looks good to me. :)

'MSI Documentations Documentation' Is that what it's supposed to be?

Probably not. You can edit the name in conf.py.

From: NCDS
Looks good to me. :)

'MSI Documentations Documentation' Is that what it's supposed to be?

Yeah, no. :p

I'll be fixing that later today. I'll probably do the comments for a couple other files also.

Did Banking.simba.

Guys, if you have a spare couple minutes, even if you only do one or two functions, that's still a big help. If we all did a couple functions a day, it'd be done in no time. :)

E: Updated the first post with a list.

E2: Did Manipulation.simba + moved some functions to it.

E3: Done Debug.simba.

Also, if there's a procedure/function with several parameters, each parameter should be explained in a list format. See MSI_AddToProggy in Debug.simba for an example of how to do it and what it looks like.

E4: Moved to public. :)

If you want to help out that would be awesome. Even if it's only a couple functions, anything is appreciated. The faster we can get this done the better.

E: Did obstacles.simba and walking_reflection.simba.

See http://docs.villavu.com/msi for the newest version. (Updated every hour or so)

You should really check out the use of implicit links. You should just link to things rather than saying ``refer to.''
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-targets

From: Nava2
You should really check out the use of implicit links. You should just link to things rather than saying ``refer to.''
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#hyperlink-targets

I figured there was something like that, thanks. :)

I also just committed the Walking_Color.simba documentation.

Done Animating.simba and Magic.simba.

Done Setup, Scripts, Walking, and Reports.

E: Done globals.

Documentation is now done with the exception of cooking, which will be done when NCDS is done implementing the skill. :)

Incredible, good job. :)

Thank you. :)