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

Thu Apr 27 09:55:04 EDT 2006

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