Hi everybody!
As you all know to successfully understand and use Panda it is important to first go through the Manual and eventually use it in parallel with the API reference pages. Short of going through the source code (certainly an instructive possibility in many circumstances) Manual and API reference should help with most of a developer’s needs.
One problem I’m noticing however is that the automatically generated documentation for classes and methods relies of course on the developer appropriately documenting the source code. Even if this has been done properly the descriptions cannot be further expanded by third-party developers who might be able to clarify concepts, add usage examples and share knowledge obtained through precious hands-on experience.
Conceptually it might appear that as the API pages are automatically overwritten with every new release of Panda there wouldn’t be much of a point in allowing user-generated documentation in them: it would get deleted when the next version is released! And technically it might appear difficult if not impossible to limit the third-party editing only to the user-generated portions of the text, while keeping the automatically generated sections locked.
In practice, and given the current setup, it is technically feasible and is not particularly difficult in MediaWiki to do so while guaranteeing persistence of the user-generated documentation across releases.
The key is in the use of Mediawiki’s templates to transclude (including) in one page the content of another. In this context an API reference page would contain the automatically generated content plus, for every class and method, transcluding templates such as {{ugd:aClass::aMethod}}, i.e.:
<b>aClass</b>
from pandac.PandaModules import aClass
Class : aClass
Description : <automatically generated documentation>
User generated documentation:
{{ugd:aClass}}
aMethod
Description: <automatically generated documentation>
User generated documentation:
{{ugd:aClass::aMethod}}
This would include in the otherwise static and locked reference page the content of the user-editable pages “aClass” and “aClass::aMethod” from the “ugd” (user-generated documentation) namespace.
As the current documentation is version-unaware with each new release the templates in the newly generated documentation page would conveniently reference the already existing user-generated documentation page for a given class or method. If we then wanted to switch to a system where the API reference for multiple releases are kept online at the same time all that would be needed is for the version number to be included in the page names, and for a mediawiki bot to copy the content of, say, page “ugd:1.6.2/aClass::aMethod” to page “ugd:1.6.3/aClass::aMethod”.
In general this is part of the solution to a problem I’m seeing in the forum, where a lot of interesting knowledge is accumulating in the discussion threads, often about specific classes and methods, but doesn’t find its way in the documentation where it belongs, and where it would prevent the same issues from being raised over and over again. Needless to say this would especially ease the support burden on Panda’s developers that could then spend more of their precious time doing what they probably like to do most: expand and strengthen Panda and of course deal with their own games.
What do you guys think?
Manu