Re: [Numpy-discussion] NumPy documentation

[David G. <dav...@gm...>]

What about the documentation that already exists here: http://www.tramy.us/

I think the more people that buy it the better since that money goes to
support Travis does it not?

Dave

On 8/5/06, Albert Strasheim <fu...@gm...> wrote:
>
> Hello all
>
> With NumPy 1.0 mere weeks away, I'm hoping we can improve the
> documentation
> a bit before the final release. Some things we might want to think about:
>
> 1. Documentation Sprint
>
> This page:
>
> http://www.scipy.org/SciPy2006/CodingSprints
>
> mentions a possible Documentation Sprint at SciPy 2006. Does anybody know
> if
> this is going to happen?
>
> 2. Tickets for missing functions missing docstrings
>
> Would it be helpful to create tickets for functions that currently don't
> have docstrings? If not, is there a better way we can keep track of the
> state of the documentation?
>
> 3. Examples in documentation
>
> Do we want to include examples in the docstrings? Some functions already
> do,
> and I think think this can be quite useful when one is exploring the
> library.
>
> Maybe the example list:
>
> http://www.scipy.org/Numpy_Example_List
>
> should be incorporated into the docstrings? Then we can also set up
> doctests
> to make sure that all the examples really work.
>
> 4. Documentation format
>
> If someone wants to submit documentation to be included, say as patches
> attached to tickets, what kind of format do we want?
>
> There's already various PEPs dealing with this topic:
>
> Docstring Processing System Framework
> http://www.python.org/dev/peps/pep-0256/
>
> Docstring Conventions
> http://www.python.org/dev/peps/pep-0257/
>
> Docutils Design Specification
> http://www.python.org/dev/peps/pep-0258/
>
> reStructuredText Docstring Format
> http://www.python.org/dev/peps/pep-0287/
>
> 5. Documentation tools
>
> A quick search turned up docutils:
>
> http://docutils.sourceforge.net/
>
> and epydoc:
>
> http://epydoc.sourceforge.net/
>
> Both of these support restructured text, so that looks like the way to go.
> I
> think epydoc can handle LaTeX equations and some LaTeX support has also
> been
> added to docutils recently. This might be useful for describing some
> functions.
>
> Something else to consider is pydoc compatibility. NumPy currently breaks
> pydoc:
>
> http://projects.scipy.org/scipy/numpy/ticket/232
>
> It also breaks epydoc 3.0a2 (maybe an epydoc bug):
>
>
> http://sourceforge.net/tracker/index.php?func=detail&aid=1535178&group_id=32
> 455&atid=405618
>
> Anything else? How should we proceed to improve NumPy's documentation?
>
> Regards,
>
> Albert
>
>
> -------------------------------------------------------------------------
> Take Surveys. Earn Cash. Influence the Future of IT
> Join SourceForge.net's Techsay panel and you'll get the chance to share
> your
> opinions on IT & business topics through brief surveys -- and earn cash
> http://www.techsay.com/default.php?page=join.php&p=sourceforge&CID=DEVDEV
> _______________________________________________
> Numpy-discussion mailing list
> Num...@li...
> https://lists.sourceforge.net/lists/listinfo/numpy-discussion
>



-- 
David Grant
http://www.davidgrant.ca