[Moin-user] Any interest in making Doxygen the standard doc tool for MoinMoin?

[Kenneth McDonald]

epydoc is a nice piece of work (and has become much more competent since 
the last time I looked at it), but unless I'm missing something, it is 
still basically an API documentation generation tool. Doxygen is a 
completely different beast. It can be, and is, used to document 
codebases in many, many different places, including at a large number of 
companies. However, it is flexible enough to be used for many other 
types of documentation, including user documentation; for example, the 
doxygen user's manual (which is quite large and comprehensive) was 
written in doxygen.

But if we could settle on epydoc as a standard, I'd support that too.

My main incentive for proposing something like this comes from going 
over "multiconfig.py" recently. I came a across a good number of useful 
features in it that either weren't documented, or weren't adequately 
documented, in the wiki documentation. In addition, I suspected that 
documentation on the wiki for some of these features had become out of date.

As a tech writer, this is an observation I've made; if user 
documentation is not part of the codebase, and you don't have a big 
documentation team checking things constantly, then your user docs can 
easily get out of sync with your product. Of course, this can happen 
regardless, but it's easier to keep the two consistent when someone 
who's reading or writing the source can immediately add or change 
documentation in the same file as necessary.

So I was wondering if there would be any interest in using some sort of 
source documentation tool to generate basic but (hopefully) definitive 
documentation of wiki features, with "higher-level" concepts being 
handled at the wiki level.

Thoughts?
Thanks,
Ken



Zoom.Quiet wrote:
> On 4/26/06, Kenneth McDonald <kenneth.m.mcdonald at sbcglobal.net> wrote:
>   
>>  From what I can see right now (please correct me if I'm wrong),
>> MoinMoin documentation is currently spread out between the code and the
>> wiki, and it is not guaranteed that the two are in sync.
>>
>> Doxygen is a superb documentation tool that supports Python, amongst
>> many other languages. Think of it as Javadoc on steroids and done right.
>> Among other things, it allows documentation--even user documentation--to
>> be placed within the source code. You can read more about it at
>> http://www.stack.nl/~dimitri/doxygen/.
>>
>>     
> ??? in Python world, there's great document sys : Epydoc
> is better for Python app. API document auto build....
>   
>> I, for one, would be happy to contribute to documentation about Moin,
>> but find the wiki too unstructured for my tastes. (I'm a tech writer by
>> trade). Amongst other things, it makes it very difficult to ensure that
>> docs on the wiki are actually up to data for the current Moin version.
>> On the other hand, if I were going through multiconfig.py (as I just
>> was), I could simply add the necessary doxygen comments, and then do
>> whatever is necessary to get the documented multiconfig.py into the
>> source tree. The next time doxygen was run, everything would be
>> generated in pretty HTML.
>>
>> Thoughts for or against?
>> Thanks,
>> Ken
>>
>>
>> -------------------------------------------------------
>> Using Tomcat but need to do more? Need to support web services, security?
>> Get stuff done quickly with pre-integrated technology to make your job easier
>> Download IBM WebSphere Application Server v.1.0.1 based on Apache Geronimo
>> http://sel.as-us.falkag.net/sel?cmd=lnk&kid=120709&bid=263057&dat=121642
>> _______________________________________________
>> Moin-user mailing list
>> Moin-user at lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/moin-user
>>
>>     
>
>
> --
> """Time is unimportant, only life important!
> blogging  :  http://blog.zoomquiet.org/pyblosxom/
> wiki enter:   http://wiki.woodpecker.org.cn/moin/ZoomQuiet
> in douban:  http://www.douban.com/people/zoomq/
> """
> Rȧ�:&q�[���y�hv����^y�h��i��py�
��z�
r��!���n}�h�ꮉ�%����ފ{^���y�^r薈2����쨺��m欉�ã	塧HŞm*az����bq�b�t���]5m�
v���!xg��x��m���zV���ږF�����\�ОI"t
> ӽ=n'ۭ��Z�
> ׮62���ǫ����x%��L�)����l���q���z�m��?�X���(��
~��zw��X�����b��?����ǫ