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

Thu Apr 27 10:02:02 EDT 2006

I wasn't going to chime in, because any documentation work in the Moin project is good work.

However, I think I need to ask an obvious question.

Wouldn't it be good to support writing documentation in Wiki Markup Language in the source python files?  That should provide a simple mechanism to generate Wiki pages of documentation for the MoinMaster wiki (one wiki page per Moin source file.)

]<eith

If a cute saying or a pretty poster is all it takes to motivate you, you probably have a very easy job.  The kind that robots will be doing soon. 

>-----Original Message-----
>From: moin-user-admin at lists.sourceforge.net [mailto:moin-user-
>admin at lists.sourceforge.net] On Behalf Of Robert Schumann
>Sent: Thursday, April 27, 2006 10:55 AM
>To: Kenneth McDonald
>Cc: moin-user at lists.sourceforge.net
>Subject: Re: [Moin-user] Any interest in making Doxygen the standard
>doctool for MoinMoin?
>
>Formalising Moin documentation is a very good idea, and something I'd be
>keen to have a hand in.
>
>Thus far, I've been using epydoc to put together my own documentation
>(as well as grep to quickly find something in the source).  I've used
>epydoc because it is extremely easy to use (took me less than a minute
>from installing it the first time to looking at documentation).
>
>I have come across Doxygen docs before, for C++ <shudder>.  I know
>little about it, but perhaps we could put a page on the MoinMoin site
>and ask for votes/comments?  Are there any other candidate doc systems?
>
>I'm assuming the developers would be enthusiastic about using automated
>documentation?  What's been your experience in the past?  Are the
>docstrings well-maintained?
>
>Robert.
>
>On Thu, 2006-04-27 at 11:21 -0500, Kenneth McDonald wrote:
>> 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��?����ǫ
> <
> <
> <
> <
>> -------------------------------------------------------
>> 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&kid0709&bid&3057&dat1642
>> _______________________________________________
>> Moin-user mailing list
>> Moin-user at lists.sourceforge.net
>> https://lists.sourceforge.net/lists/listinfo/moin-user
>
>
>
>-------------------------------------------------------
>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=k&kid0709&bid&3057&dat1642
>_______________________________________________
>Moin-user mailing list
>Moin-user at lists.sourceforge.net
>https://lists.sourceforge.net/lists/listinfo/moin-user