[SciPy-dev] Docstring editing request on SciPy Doc Wiki

Pauli Virtanen pav@iki...
Mon May 19 14:26:35 CDT 2008


ma, 2008-05-19 kello 12:31 -0500, Robert Kern kirjoitti:
> On Mon, May 19, 2008 at 12:19 PM, Stéfan van der Walt <stefan@sun.ac.za> wrote:
[clip]
> > So rather than a technological limitation, I see it as a matter of
> > courtesy.
> 
> I'm wondering if there isn't a technical solution, though. Is the code
> available somewhere? I can answer these questions myself if it is.

See here: http://sd-2116.dedibox.fr/wiki/numpydoc/
(Note that you can bzr clone this.)

Currently the workflow is roughly like so:

1) Collect docstrings: (see pydoc.dtd)

  pydoc_moin collect source-tree module > docstrings.xml

2) Upload docstrings (overwrite current ones):

  pydoc_moin moin-upload-local /moin_location < docstrings.xml

3) Download docstrings

  pydoc_moin moin-collect-local /moin_location > new_docstrings.xml

4) Replace docstrings in sources, one bzr commit per docstring

  pydoc_moin bzr docstrings.xml new_docstrings.xml bzr-tree

4b) Or make a patch

  pydoc_moin patch docstrings.xml new_docstrings.xml source-tree > docs.patch


What happens after this is up to the person doing the merge.

If the source tree is indeed managed with bzr, one could use its merge
capabilities for doing all the merges, conflict resolution, or cherry
picking. At the moment it seems to me that the "correct" workflow for
this case would be to

  - Always keep the wiki bzr branch in sync with the stuff in the wiki.
    (Wiki needs to be locked at some point so that we don't
accidentally
     overwrite change not in bzr.)

  - Periodically merge wiki's bzr branch with SVN, resolve conflicts,
    and push changes back to the wiki. 
    (But don't push changes in wiki back to SVN.)

  - At times, cherry-pick good docstrings to SVN.
    I'm not sure bzr is smart enough to mark these as no-op merges
    when merging the changes back to wiki's bzr branch.

But I think Stéfan had objections to this workflow?


Some drawbacks in the above mechanism are:
  a) Everything must be merged at once.
  b) Responsibility for a single merge is concentrated 
     on a single person.

A fix for a) could be to do 3-way merging ourselves and not rely on bzr.
We'd need to track the base revision and handle conflict resolution.
Luckily, the code that would handle merging needs only to munge XML
files and ask the user what to do on conflicts.

If we want to allow anyone to handle conflict resolution (to get rid of
b), then merging would need to be pushed down to the wiki level, which
could lead to a mess. But it would probably be doable in a custom
web-app.

-- 
Pauli Virtanen




More information about the Scipy-dev mailing list