Documenting the Python code, a proposal

[pholtz]

I am new to python and Civ4 modding, so I hope I'm not to off base, but here goes

I finally figured out how to get pyDoc help for the Civ4 modules. The following is the output for pyDoc help for my CvCustomEventManager:

load_module pydoc
Help on module CvCustomEventManager:

NAME
    CvCustomEventManager

FILE
    c:\program files\firaxis games\sid meier's civilization 4\assets\python\cvcustomeventmanager.py

CLASSES
    CvEventManager.CvEventManager
        CvCustomEventManager
    
    class CvCustomEventManager(CvEventManager.CvEventManager)
     |  Methods defined here:
     |  
     |  __init__(self)
     |  
     |  onGameStart(self, argsList)
     |  
     |  ----------------------------------------------------------------------
     |  Methods inherited from CvEventManager.CvEventManager:
     |  
     |  applyEvent(self, argsList)
     |      Apply the effects of an event
     |  
     |  beginEvent(self, context, argsList=-1)
     |      Begin Event
     |  
     |  handleEvent(self, argsList)
     |      EventMgr entry point
     |  
     |  onBeginGameTurn(self, argsList)
     |      Called at the beginning of the end of each turn
     |  
     |  onBeginPlayerTurn(self, argsList)
     |      Called at the beginning of a players turn
     |  
     |  onBuildingBuilt(self, argsList)
     |      Building Completed
     |  
     |  onChangeWar(self, argsList)
     |      War Status Changes
     |  
     |  onChat(self, argsList)
     |      Chat Message Event
     |  
     |  onCityAcquired(self, argsList)
     |      City Acquired
     |  
     |  onCityBuildingBuilding(self, argsList)
     |      City begins building a Building
     |  
     |  onCityBuildingUnit(self, argsList)
     |      City begins building a unit
     |  
     |  onCityBuilt(self, argsList)
     |      City Built
     |  
     |  onCityDoTurn(self, argsList)
     |      City Production
     |  
     |  onCityGrowth(self, argsList)
     |      City Population Growth
     |  
     |  onCityLost(self, argsList)
     |      City Lost
     |  
     |  onCityRazed(self, argsList)
     |      City Razed
     |  
     |  onCityRename(self, argsList)
     |      City is renamed
     |  
     |  onCombatLogCalc(self, argsList)
     |      Combat Result
     |  
     |  onCombatLogHit(self, argsList)
     |      Combat Message
     |  
     |  onCombatResult(self, argsList)
     |      Combat Result
     |  
     |  onCultureExpansion(self, argsList)
     |      City Culture Expansion
     |  
     |  onEndGameTurn(self, argsList)
     |      Called at the end of the end of each turn
     |  
     |  onEndGoldenAge(self, argsList)
     |      End Golden Age
     |  
     |  onEndPlayerTurn(self, argsList)
     |      Called at the end of a players turn
     |  
     |  onEndTurnReady(self, argsList)
     |  
     |  onFirstContact(self, argsList)
     |      Contact
     |  
     |  onGameEnd(self, argsList)
     |      Called at the End of the game
     |  
     |  onGameUpdate(self, argsList)
     |      sample generic event, called on each game turn slice
     |  
     |  onGoldenAge(self, argsList)
     |      Golden Age
     |  
     |  onGoodyReceived(self, argsList)
     |      Goody received
     |  
     |  onGreatPersonBorn(self, argsList)
     |      Unit Promoted
     |  
     |  onImprovementBuilt(self, argsList)
     |      Improvement Built
     |  
     |  onInit(self, argsList)
     |      Called when Civ starts up
     |  
     |  onKbdEvent(self, argsList)
     |      keypress handler - return 1 if the event was consumed
     |  
     |  onLoadGame(self, argsList)
     |  
     |  onMouseEvent(self, argsList)
     |      mouse handler - returns 1 if the event was consumed
     |  
     |  onPlotRevealed(self, argsList)
     |      Plot Revealed
     |  
     |  onPreSave(self, argsList)
     |      called before a game is actually saved
     |  
     |  onProjectBuilt(self, argsList)
     |      Project Completed
     |  
     |  onReligionFounded(self, argsList)
     |      Religion Founded
     |  
     |  onReligionSpread(self, argsList)
     |      Religion Has Spread to a City
     |  
     |  onRouteBuilt(self, argsList)
     |      Route Built
     |  
     |  onSaveGame(self, argsList)
     |      return the string to be saved - Must be a string
     |  
     |  onSetPlayerAlive(self, argsList)
     |      Set Player Alive Event
     |  
     |  onTechAcquired(self, argsList)
     |      Tech Acquired
     |  
     |  onTechSelected(self, argsList)
     |      Tech Selected
     |  
     |  onUnInit(self, argsList)
     |      Called when Civ shuts down
     |  
     |  onUnitBuilt(self, argsList)
     |      Unit Completed
     |  
     |  onUnitCreated(self, argsList)
     |      Unit Completed
     |  
     |  onUnitKilled(self, argsList)
     |      Unit Killed
     |  
     |  onUnitLost(self, argsList)
     |      Unit Lost
     |  
     |  onUnitMove(self, argsList)
     |      unit move
     |  
     |  onUnitPromoted(self, argsList)
     |      Unit Promoted
     |  
     |  onUnitRename(self, argsList)
     |      Unit is renamed
     |  
     |  onUnitSelected(self, argsList)
     |      Unit Selected
     |  
     |  onUnitSetXY(self, argsList)
     |      units xy coords set manually
     |  
     |  onUpdate(self, argsList)
     |      Called every frame
     |  
     |  onVictory(self, argsList)
     |      Victory
     |  
     |  onWindowActivation(self, argsList)
     |      Called when the game window activates or deactivates
     |  
     |  reportEvent(self, entry, context, argsList)
     |      Report an Event to Events.log

DATA
    __loader__ = <__main__.myImportHandler instance>
    __version__ = '$Revision: 1.3 $'
    false = 0
    gc = <CvPythonExtensions.CyGlobalContext object>
    localText = <CvPythonExtensions.CyTranslator object>
    true = 1

VERSION
    1.3

As you can see it prints out all the method documention of the parent. If I had a clean mod and then just copied CvEventManager to my mod I could get clean documention of the original module.

I managed this my turning on the logs, then inserting

help("CvCustomEventManager")

into the __init__ method.

Here is my proposal (actually two):

1. I would be glad to get clean pyDoc help texts for all the modules that I can. In fact I'll probably do it myself for my own purposes. Would anyone be interested in a copy? Is there any place for me to upload this.

2. The documention is somewhat sparse. For example, there is no explanation of what is expected in argList for all the events. Now I am brand new to this and really can't add much good documention. But with the help of some of you experts, you could put in more complete documentation (comments) in the modules, I could then print out help docs that are much more complete and helpful. Perhaps even Firaxis would be interested in incorporating more complete comments into their original versions? I don't know who to ask about this or to get it started.

Any comments or further ideas along this line? Has the whole thing already been done somewhere?

 

[pholtz]

Not quite sure why the lack of interest. I'm having touble figuring out all the python code and I'm sure some of you are too. To try to get things going here's a file with the pydoc help for 11 different modules. You can see that the auto documention is of varied help depending on the comments in the module.

 

[Padmewan]

Is this not helpful?

http://sthurlow.com/cvDocs/

(There's a better one, but I don't have the URL handy)

 

[Gerikes]

While it seems like a cool idea, but like Lord Olleus said, most of the code is farily self-explanitory. For all the code that might be a bit more confusing, I think a wiki is a better idea. The main reason is that you don't need to download anything and install to look at the docs. TheGreatApple I believe has one up, but I don't know how much gets put into it.

That's not to say that there wasn't a few times that I wished all the Civ4 functions had pydocs available whenever I was trying to figure out how to do something in the in-game shell (especially when it comes to the long argument lists), but I think it would just be better if all that was documented on a wiki or using a website like Padmewan showed.

 

[The Great Apple]

For all the code that might be a bit more confusing, I think a wiki is a better idea. The main reason is that you don't need to download anything and install to look at the docs. TheGreatApple I believe has one up, but I don't know how much gets put into it.

It's not mine - I just link to it in my sig

Personally I don't think I have a use for such a thing, as I've learnt my way around the python files by poking around with them. I can see it being useful for people seeing the code for the first time however.

 

[Jeckel]

Isn't what pholtz suggests the same thing as Locutus's API?

However the idea of explanations for what each, or atleast the most important, method does is a good one. I wish I'd had somthing to tell me that finishMoves() was the way to end a units movement. I keep meaning to go on the wiki and add some info, but you know how it is, time constraints and always another intersting idea to play with.

 

[The Great Apple]

Isn't what pholtz suggests the same thing as Locutus's API?

No - the API documents the C++ code. This would document the python code.

However the idea of explanations for what each, or atleast the most important, method does is a good one. I wish I'd had somthing to tell me that finishMoves() was the way to end a units movement. I keep meaning to go on the wiki and add some info, but you know how it is, time constraints and always another intersting idea to play with.

The problem is often finding the function in the first place, rather than knowing what it does when you do spot it. There's little that can be done to help this, apart from having less functions to look through!

Actually I supose they could be catagorised in some way - all the unit movements ones have a certain catagory, for example.

 

[Padmewan]

What would really be helpful -- and maybe this is already out there and I haven't found it -- is a top-down guide to how the Python functions fit into the core game engine, e.g. in what order are they called, and what they generally do. For example, without communicating with Kael directly, I would not have thought that GameInterface.py contained such helpful Python-based "checks" for whether a civ can use a civic or not. (Deconstructing Desert War would have yielded the answer as well). I still don't quite understand how the functions in that file are called -- is it a "glue" layer between C++ and the actual game you see, or a module that C++ calls and then does more magic with before spitting it out?

Even basic syntax like Civ's own pecular method of "Includes" would be helpful.

 

[A Silly Goose]

I myself know that it'd be great if I could look up a function and see exactly what it does, what it's arguments are, etc.

Yes, the code may be self-explanatory, but only if you're already familiar with python. Those of us who don't know, like myself, would have a much easier time learning to mod with it, though, if there were extensive documentation.

I know that I myself would like to try learning the Way of the Python, but it's not exactly practical to just dive into it when you've got as crazy a year as mine going on--dad's opening multiple new branches for his company, grandpa breaks a hip, grandma was ill as well, mom was made state media specialist of the year and decided to apply for national board certification, both parents keep having to go out of town constantly, the spring semester just ended and I gotta go find a job, the dog is getting old and has started making a mess everywhere, the basement of the lake house got flooded from a burst pipe, I've never seen a year so chock-full of upcoming gaming masterpieces that I'll have to buy and play... Oh, and that reminds me, I've gotta get my Gamecube repaired, too...

...Sorry, I just had to get that off my chest--but at least you get the point.