[Biopython-dev] Documentation Status

Travis Wrightsman twrig002 at ucr.edu
Tue Oct 14 17:10:18 UTC 2014


I finished translating the obviously labeled epytext doc strings to proper reStructuredText. Now I'm working through each error/warning that the epydoc compiler is spitting out. When I've finished this I'll submit a pull request for you all to review before merging.

When it's all merged and done, I can start attempting to compile in Sphinx, just to test.

Travis Wrightsman

> On Oct 14, 2014, at 6:56 AM, Yanbo Ye <yeyanbo289 at gmail.com> wrote:
> 
> Hi Peter and Alexey,
> 
> The main documentation can be stored in rst files. I think the way I suggest can let potential contributors know where to start the translation, although some languages may not have so many contributors. Anyway, this make things more complicated with docstrings and transifex. If the main tutorial will be continuing in LaTex format, I think a guide to how to translate it will be very helpful.
> 
>> On Tue, Oct 14, 2014 at 9:01 PM, Peter Cock <p.j.a.cock at googlemail.com> wrote:
>> Hi Alexey,
>> 
>> I would agree there is no need to translate the docstrings (and
>> there is no easy way to do it either at the source code level).
>> [Note we would like to have them all RST formatted to make the
>> API documentation prettier, i.e. using reStructuredText]
>> 
>> I would focus any translation efforts on the main Tutorial,
>> which is currently written in LaTeX:
>> https://github.com/biopython/biopython/blob/master/Doc/Tutorial.tex
>> 
>> There are also user contributed "Cookbook" examples on our
>> wiki - would people want to translate any of these?
>> http://biopython.org/wiki/Category:Cookbook
>> 
>> And various people have written introduction slides for workshops
>> etc over the years, e.g. mine using *.rst on GitHub:
>> https://github.com/peterjc/biopython_workshop
>> 
>> Peter
>> 
>> 
>> On Tue, Oct 14, 2014 at 1:45 PM, Alexey Morozov
>> <alexeymorozov1991 at gmail.com> wrote:
>> > Not really, if the main bulk of documentation is to be stored in docstrings
>> > or made from them automatically for every future release. These things go
>> > untranslated for years for less common languages, cause problems with
>> > non-ASCII characters and so on.
>> >
>> > But I think that there is not much need for translated docstrings. At least
>> > in Russia, everyone in IT/CS and nearly everyone in life sciences knows at
>> > least some English. What I was talking about is multilingual wiki or at
>> > least a few manuals, cookbooks and "Getting started"s, or maybe Biopython
>> > workshop, because it may help bioinformatics teachers.
>> >
>> >
>> > 2014-10-14 19:36 GMT+09:00 Peter Cock <p.j.a.cock at googlemail.com>:
>> >>
>> >> Hi Alexey,
>> >>
>> >> I am not aware of any Russian translation (another interesting language
>> >> in terms of non-ASCII characters and the potential markup implications).
>> >>
>> >> Do you have any thoughts on if and how to track any future translation
>> >> work in the main Biopython repository side by side with the English
>> >> version to help keep things up to date?
>> >>
>> >> Peter
>> >>
>> >> On Tue, Oct 14, 2014 at 11:32 AM, Alexey Morozov
>> >> <alexeymorozov1991 at gmail.com> wrote:
>> >> > Speaking of translations, is Biopython documentation being translated
>> >> > into
>> >> > Russian? I could contribute to such a work, but definitely won't make it
>> >> > all
>> >> > alone.
>> >> >
>> >> > 2014-10-14 18:48 GMT+09:00 Peter Cock <p.j.a.cock at googlemail.com>:
>> >> >>
>> >> >> Hi Yanbo,
>> >> >>
>> >> >> Translations are an interesting case - some of the tutorial was also
>> >> >> translated into Japanese once, but this work often goes out of date :(
>> >> >> Using LaTeX it would be possible to embed alternative versions
>> >> >> into the same file - even at a chapter or section level (you can have
>> >> >> conditional blocks with if statements - so new sections could be in
>> >> >> English only initially while waiting for translation). I don't think
>> >> >> you
>> >> >> can do this with Sphinx - or can you?
>> >> >>
>> >> >> Peter
>> >> >>
>> >> >> P.S. The source files for the Chinese translation is here, plus a port
>> >> >> of the LaTeX tutorial into *.rst:
>> >> >> https://github.com/bigwiv/Biopython-cn
>> >> >>
>> >> >>
>> >> >> On Tue, Oct 14, 2014 at 10:00 AM, Yanbo Ye <yeyanbo289 at gmail.com>
>> >> >> wrote:
>> >> >> > For the Tutorial of Sphinx, here is a Chinese version that we
>> >> >> > translated
>> >> >> > last year. All format seems ok, including  equations, chapter
>> >> >> > hyperlinks,
>> >> >> > references, etc. But it cannot pass the pdf compiling process on
>> >> >> > readthedocs.  I'm not a expert on this. Maybe someone can give it a
>> >> >> > try.
>> >> >> >
>> >> >> > http://biopython-cn.readthedocs.org/zh_CN/latest/index.html
>> >> >> _______________________________________________
>> >> >> Biopython-dev mailing list
>> >> >> Biopython-dev at mailman.open-bio.org
>> >> >> http://mailman.open-bio.org/mailman/listinfo/biopython-dev
>> >> >
>> >> >
>> >> >
>> >> >
>> >> > --
>> >> > Alexey Morozov,
>> >> > LIN SB RAS, bioinformatics group.
>> >> > Irkutsk, Russia.
>> >
>> >
>> >
>> >
>> > --
>> > Alexey Morozov,
>> > LIN SB RAS, bioinformatics group.
>> > Irkutsk, Russia.
> 
> 
> 
> -- 
> 
> Yanbo Ye
> Guangzhou Institutes of Biomedicine and Health, 
> Chinese Academy of Sciences
> 190 Kaiyuan Avenue, Science Park, Guangzhou, China
> 
> Email: ye_yanbo at gibh.ac.cn
> Web: http://www.yeyanbo.com
> Phone: (86)-020-32093810
> _______________________________________________
> Biopython-dev mailing list
> Biopython-dev at mailman.open-bio.org
> http://mailman.open-bio.org/mailman/listinfo/biopython-dev
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.open-bio.org/pipermail/biopython-dev/attachments/20141014/f91bbb9d/attachment-0001.html>


More information about the Biopython-dev mailing list