[SciPy-Dev] Contributing to the Documentation

[Ralf Gommers]

On Fri, Aug 2, 2013 at 8:12 PM, Cera, Tim <tim at cerazone.net> wrote:

> On Fri, Aug 2, 2013 at 11:33 AM, Juan Luis Cano <juanlu001 at gmail.com>wrote:
>
>>  On 08/01/2013 11:29 PM, Ralf Gommers wrote:
>>
>> Not a huge amount, but still regular edits (thanks mainly to Tim Cera)
>> adding up to 1000s of words for every release. The wiki also has some
>> advantages if you'd want to edit larger amounts of docs, like a system to
>> indicate if a docstring is draft / for review / reviewed, and the option to
>> render a page (helps to fix formatting issues). But yes, overall I'd still
>> prefer PRs over wiki edits.
>>
>>
> I got used to the editor.  And I am now going to type a bit of heresy: I
> use git, but I really don't like it.  The complexity/benefit ratio is too
> high for my poor brain.
>
> There is an overlooked advantage to the editor in that when edits are
> previewed there are several tests that validate the docstring you are
> working on.  Those tests could be made part of the test suite (and
> expanded), but currently they are only in the on-line editor.
>

We could only do that after fixing all current formatting issues in the
complete code base (and there will be a lot). After that's done, such a
test would indeed be useful.


> Also, there are bug fixes and additional features in the development
> version of pydocweb that would be nice to see in the on-line doc editor.
>  Actually, these might have been implemented, apologies if anyone has
> already done this - haven't been on in awhile.
>
> And in terms of editing the docstrings, there are many discussions,
> comments, ...etc. about different format issues that are scattered across
> the e-mail list, the discussion section of the on-line editor - but very
> few decisions.  Really would be helpful to codify all of these discussions
> into decisions, write them down, AND implement them as tests.
>

I've tried to keep
https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt up to
date with any decisions made on formatting. If you see gaps in that
document, please open an issue for those (or edit the text in the Github
editor interface:) ).

Ralf



>
> Kindest regards,
> Tim
>
>
> _______________________________________________
> SciPy-Dev mailing list
> SciPy-Dev at scipy.org
> http://mail.scipy.org/mailman/listinfo/scipy-dev
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/scipy-dev/attachments/20130804/ba296cdb/attachment.html>