[IPython-dev] IPython documentation

[Brian Granger]

On Wed, Jun 11, 2008 at 6:58 PM, Fernando Perez <fperez.net@gmail.com> wrote:
> On Wed, Jun 11, 2008 at 3:35 PM, Brian Granger <ellisonbg.net@gmail.com> wrote:
>> Hello all,
>>
>> So, I have finished merging in the ipython1 documentation into IPython
>> proper.  Now all the docs are in one place.
>>
>> In addition to doing this merge, I have taken the liberty of
>> completely reorganizing the docs.  Previously, the IPython docs were a
>> single rst file, which was really awkward and didn't take advantage of
>> Sphinx's nice features.  In the process of doing all this, I realized
>> that the IPython docs (not the parallel computing stuff) need quite a
>> bit of care and attention.  I would like to see if we can get people
>> to put in time to get our docs back up to where they should be.  Here
>> is what I am thinking:
>
> Thanks for doing this, it was needed.  For one thing, search was
> broken with the single-file one.
>
> One thing that I've been mulling is using the new scipy doc system
>
> http://sd-2116.dedibox.fr/pydocweb/wiki/Front%20Page/
>
> for the manuals as well.  I know it's doable, I just don't know right
> now how closely tied to docstring editing (the original purpose) it
> is.  Stefan can tell us...

Something like this would be a huge help.  I agree with you that it is
likely that it can be done, but we would need to make sure that it can
handle all of the custom Sphinx rst directives.  I would be very
curious to heard from Stefan on this

At the same time, I strongly feel that our new Sphinx/rst based docs
are nice enough that we have no excuses for not writing great
documentation :)



Brian




> Cheers,
>
> f
>