[Biopython-dev] Porting docs to sphinx #3220

[Peter Cock]

On Tue, Jun 12, 2012 at 8:03 PM, Colin Lappala <lappc at u.washington.edu> wrote:
> Hi,
>
> I'd like to contribute to feature #3220. I am interested in learning more
> about the parts and details of Biopython that I haven't used yet, as well
> as getting involved in this project somehow. I am familiar with Sphinx,
> git, and parts of Biopython, and would love the chance to help out. I have
> taken a stab at using Sphinx to semi-automatically generate the
> documentation on a project in our lab (which is not in its final form yet):
> http://depts.washington.edu/cshlab/xpression/html/rnaseq.shtml.

You certainly should be in a good position to help :)

> If I can help, I had a few questions first:
>
> 1) I see that you want to keep with Numpy-type rST formatting, but I
> haven't seen the current thought on how to avoid using the :class:`class`
> type of markup in the mailing list logs.

What do NumPy use? How about just not marking classes in any
special way in the short term.

> 2) How should I go about dividing the task, since there may be other people
> at work on it as well? I've branched biopython on github, but wanted to
> know which modules' docstrings are being ported so I could work on the
> other ones.

I assume you're talking about using restructured text in the docstrings,
right? (Moving the tutorial from LaTeX to restructured text is a much
bigger job and less important in my view).

I think the simple answer is to announce you're planning to work on a
particular module here, to check if no one else is doing it, or making
other changes in that area of the code (e.g. some feature development
which might make merging doctoring changes harder).

Then make a new branch for your modifications, and when done
(and tested - for example with epydoc) make a pull request.

The epydoc command we use is listed here,
http://biopython.org/wiki/Building_a_release

epydoc -v -o ~/api -u http://biopython.org -n Biopython --docformat
plaintext Bio BioSQL

Peter