Discussion:
[Biopython - Feature #3219] (New) Port Biopython documentation to Sphinx
(too old to reply)
redmine
2011-04-28 16:09:11 UTC
Permalink
Issue #3219 has been reported by Eric Talevich.

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2011-04-28 16:09:11 UTC
Permalink
Issue #3219 has been reported by Eric Talevich.

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt



----------------------------------------
You have received this notification because this email was added to the New Issue Alert plugin
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
Kristian Rother
2011-04-29 07:37:28 UTC
Permalink
Hi,

I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!

What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.

Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?

Best regards,
Kristian
Post by redmine
Issue #3219 has been reported by Eric Talevich.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219
Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Currently we use Epydoc for the API reference documentation, and LaTeX (to
PDF via pdflatex, and HTML via hevea) for the tutorial. There's some
material on the wiki to consider, too.
A number of Python projects, including CPython, now use Sphinx for
documentation. Content is written in reStructuredText format, and can be
pulled from both standalone .rst files and Python docstrings.
This offers several advantages: (i) API documentation will be prettier and
easier to navigate; (ii) the Tutorial will be easier to edit for those not
fluent in LaTeX; (iii) Since the API reference and Tutorial will be
written in the same markup, potentially even pulling from some shared
sources, it will be easier to address redundant or overlapping portions
between the two, avoiding inconsistencies.
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
----------------------------------------
You have received this notification because this email was added to the
New Issue Alert plugin
--
You have received this notification because you have either subscribed to
it, or are involved in it.
http://redmine.open-bio.org
_______________________________________________
Biopython-dev mailing list
Biopython-dev at lists.open-bio.org
http://lists.open-bio.org/mailman/listinfo/biopython-dev
Peter Cock
2011-04-29 07:55:40 UTC
Permalink
Re: Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

and this thread last year:
http://portal.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
Post by Kristian Rother
Hi,
I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!
What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.
Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?
Best regards,
? Kristian
I think there was an experimental branch on github already... by Eric and/or
Vince, but his repository seems to have gone: https://github.com/vsbuffalo/

Peter
Eric Talevich
2011-04-29 14:13:17 UTC
Permalink
Post by Peter Cock
Re: Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219
http://portal.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
Post by Kristian Rother
Hi,
I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!
What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.
Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?
Best regards,
Kristian
I think there was an experimental branch on github already... by Eric and/or
https://github.com/vsbuffalo/
I don't have a branch for this yet, but I filed the bugs on Redmine to get
this big to-do item out of my head and onto the web. I expect to have a
little bit more time this summer to work on Bio.Phylo and Bio.PDB/Struct,
and I'm going to start by converting the docstrings in Bio.Phylo to
reStructuredText. This won't take much time, and once we merge that branch
and make the Docutils dependency official (for building Epydoc
documentation), that will reduce the activation energy for porting the rest
of our docstrings.

If anyone else wants to port some docstrings independently, that's cool too,
and I don't think it will cause any conflict in the code base.

Once that's done, we can start seriously considering the switch from Epydoc
to Sphinx. Sound like a plan?

Cheers,
Eric
Peter Cock
2011-04-29 23:47:35 UTC
Permalink
I don't have a branch for this yet, but I filed the bugs on Redmine to get this big to-do item out of my head and onto the web. I expect to have a little bit more time this summer to work on Bio.Phylo and Bio.PDB/Struct, and I'm going to start by converting the docstrings in Bio.Phylo to reStructuredText. This won't take much time, and once we merge that branch and make the Docutils dependency official (for building Epydoc documentation), that will reduce the activation energy for porting the rest of our docstrings.
If anyone else wants to port some docstrings independently, that's cool too, and I don't think it will cause any conflict in the code base.
Once that's done, we can start seriously considering the switch from Epydoc to Sphinx. Sound like a plan?
Cheers,
Eric
Yes, sounds good.

Peter
Peter Cock
2011-04-29 23:47:35 UTC
Permalink
I don't have a branch for this yet, but I filed the bugs on Redmine to get this big to-do item out of my head and onto the web. I expect to have a little bit more time this summer to work on Bio.Phylo and Bio.PDB/Struct, and I'm going to start by converting the docstrings in Bio.Phylo to reStructuredText. This won't take much time, and once we merge that branch and make the Docutils dependency official (for building Epydoc documentation), that will reduce the activation energy for porting the rest of our docstrings.
If anyone else wants to port some docstrings independently, that's cool too, and I don't think it will cause any conflict in the code base.
Once that's done, we can start seriously considering the switch from Epydoc to Sphinx. Sound like a plan?
Cheers,
Eric
Yes, sounds good.

Peter
Eric Talevich
2011-04-29 14:13:17 UTC
Permalink
Post by Peter Cock
Re: Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219
http://portal.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
Post by Kristian Rother
Hi,
I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!
What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.
Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?
Best regards,
Kristian
I think there was an experimental branch on github already... by Eric and/or
https://github.com/vsbuffalo/
I don't have a branch for this yet, but I filed the bugs on Redmine to get
this big to-do item out of my head and onto the web. I expect to have a
little bit more time this summer to work on Bio.Phylo and Bio.PDB/Struct,
and I'm going to start by converting the docstrings in Bio.Phylo to
reStructuredText. This won't take much time, and once we merge that branch
and make the Docutils dependency official (for building Epydoc
documentation), that will reduce the activation energy for porting the rest
of our docstrings.

If anyone else wants to port some docstrings independently, that's cool too,
and I don't think it will cause any conflict in the code base.

Once that's done, we can start seriously considering the switch from Epydoc
to Sphinx. Sound like a plan?

Cheers,
Eric
Peter Cock
2011-04-29 07:55:40 UTC
Permalink
Re: Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

and this thread last year:
http://portal.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
Post by Kristian Rother
Hi,
I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!
What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.
Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?
Best regards,
? Kristian
I think there was an experimental branch on github already... by Eric and/or
Vince, but his repository seems to have gone: https://github.com/vsbuffalo/

Peter
redmine
2011-04-28 16:09:11 UTC
Permalink
Issue #3219 has been reported by Eric Talevich.

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2011-04-28 16:09:11 UTC
Permalink
Issue #3219 has been reported by Eric Talevich.

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt



----------------------------------------
You have received this notification because this email was added to the New Issue Alert plugin
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
Kristian Rother
2011-04-29 07:37:28 UTC
Permalink
Hi,

I've seen Sphinx being used on several projects (see e.g.
http://pycogent.sourceforge.net/cookbook/index.html) and tried it on one
myself (2009). The system for mixing text+code and testing code examples
is gorgeous!

What I didn't like is that all Sphinx sites seem to look the same
(including font sizes and colours). There probably is a place to apply a
CSS stylesheet, but it was not easy to find. There might be some work at
this point.

Is someone trying to make a proof-of-concept on GIT or are we looking for
a volunteer?

Best regards,
Kristian
Post by redmine
Issue #3219 has been reported by Eric Talevich.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219
Author: Eric Talevich
Status: New
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Currently we use Epydoc for the API reference documentation, and LaTeX (to
PDF via pdflatex, and HTML via hevea) for the tutorial. There's some
material on the wiki to consider, too.
A number of Python projects, including CPython, now use Sphinx for
documentation. Content is written in reStructuredText format, and can be
pulled from both standalone .rst files and Python docstrings.
This offers several advantages: (i) API documentation will be prettier and
easier to navigate; (ii) the Tutorial will be easier to edit for those not
fluent in LaTeX; (iii) Since the API reference and Tutorial will be
written in the same markup, potentially even pulling from some shared
sources, it will be easier to address redundant or overlapping portions
between the two, avoiding inconsistencies.
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
----------------------------------------
You have received this notification because this email was added to the
New Issue Alert plugin
--
You have received this notification because you have either subscribed to
it, or are involved in it.
http://redmine.open-bio.org
_______________________________________________
Biopython-dev mailing list
Biopython-dev at lists.open-bio.org
http://lists.open-bio.org/mailman/listinfo/biopython-dev
redmine
2011-05-10 02:44:36 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.

Status changed from New to In Progress
% Done changed from 0 to 20

Here's a branch where I'm testing Sphinx:
https://github.com/etal/biopython/tree/sphinx-demo

There's not much there yet, so don't panic.

For reference, DendroPy has a good example of Sphinx in action:
https://github.com/jeetsukumaran/DendroPy/tree/master/doc/source/
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2011-05-10 02:44:36 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.

Status changed from New to In Progress
% Done changed from 0 to 20

Here's a branch where I'm testing Sphinx:
https://github.com/etal/biopython/tree/sphinx-demo

There's not much there yet, so don't panic.

For reference, DendroPy has a good example of Sphinx in action:
https://github.com/jeetsukumaran/DendroPy/tree/master/doc/source/
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-08 22:23:22 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


In terms of moving the Tutorial from LaTeX to Sphinx, we'd need to update Tests/test_Tutorial.py which currently tests marked doctests within the tutorial (to ensure they are in sync with the latest code).
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-14 20:58:30 UTC
Permalink
Issue #3219 has been updated by Sergei Lebedev.


Is this feature being worked on? the linked GitHub repo seems abandoned.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-14 22:52:01 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.


Colin Lappala offered to start working on this just a couple days ago:
http://lists.open-bio.org/pipermail/biopython-dev/2012-June/009708.html

I played with Sphinx a little bit when I filed this bug last year, but didn't accomplish anything significant. I am not aware of any public branch that could serve as a starting point, but in any case, the first step is to port the docstrings from epytext to reStructuredText. That part can be done in small pieces concurrently, I think.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-15 08:41:05 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


Actually most of our docstrings are just plain text (there are some in epytext), but yes, the first goal is to get all the docstrings into reStructuredText.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-15 17:26:41 UTC
Permalink
Issue #3219 has been updated by Sergei Lebedev.


Well, I think Sphinx has a huge benefit, compared to epydoc -- it generates *excellent*, easy to use API documentation. So it would be nice to see BioPython using it, since current API docs aren't very developer-friendly.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-16 00:32:36 UTC
Permalink
Issue #3219 has been updated by Paulo Nuin.


I can help with this, just need to get the files and understand the current structure a bit.


----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-18 20:26:49 UTC
Permalink
Issue #3219 has been updated by Paulo Nuin.


What is the best way to proceed and help with this issue?
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-19 15:52:20 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.
Post by redmine
What is the best way to proceed and help with this issue?
Hi Paul,

We're coordinating this effort on the biopython-dev mailing list, if you'd like to sign up and help out:
http://lists.open-bio.org/mailman/listinfo/biopython-dev

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-08 22:23:22 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


In terms of moving the Tutorial from LaTeX to Sphinx, we'd need to update Tests/test_Tutorial.py which currently tests marked doctests within the tutorial (to ensure they are in sync with the latest code).
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-14 20:58:30 UTC
Permalink
Issue #3219 has been updated by Sergei Lebedev.


Is this feature being worked on? the linked GitHub repo seems abandoned.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-14 22:52:01 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.


Colin Lappala offered to start working on this just a couple days ago:
http://lists.open-bio.org/pipermail/biopython-dev/2012-June/009708.html

I played with Sphinx a little bit when I filed this bug last year, but didn't accomplish anything significant. I am not aware of any public branch that could serve as a starting point, but in any case, the first step is to port the docstrings from epytext to reStructuredText. That part can be done in small pieces concurrently, I think.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-15 08:41:05 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


Actually most of our docstrings are just plain text (there are some in epytext), but yes, the first goal is to get all the docstrings into reStructuredText.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-15 17:26:41 UTC
Permalink
Issue #3219 has been updated by Sergei Lebedev.


Well, I think Sphinx has a huge benefit, compared to epydoc -- it generates *excellent*, easy to use API documentation. So it would be nice to see BioPython using it, since current API docs aren't very developer-friendly.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-16 00:32:36 UTC
Permalink
Issue #3219 has been updated by Paulo Nuin.


I can help with this, just need to get the files and understand the current structure a bit.


----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-18 20:26:49 UTC
Permalink
Issue #3219 has been updated by Paulo Nuin.


What is the best way to proceed and help with this issue?
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-06-19 15:52:20 UTC
Permalink
Issue #3219 has been updated by Eric Talevich.
Post by redmine
What is the best way to proceed and help with this issue?
Hi Paul,

We're coordinating this effort on the biopython-dev mailing list, if you'd like to sign up and help out:
http://lists.open-bio.org/mailman/listinfo/biopython-dev

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-07-11 17:49:47 UTC
Permalink
Issue #3219 has been updated by Wibowo Arindrarto.


Hi everyone,

Just as an FYI which may or may not be useful, I just stumbled on a Biopython sphinx documentation here: http://www.bio-cloud.info/Biopython/en/index.html. Its sphinx source says it was generated just about a year ago (July 2011).

The creator has a personal webpage, but it's not really clear how to contact him/her.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-07-11 18:13:40 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


Seems they were interested in translating it into Chinese, based on a Google translation of this post:
http://www.bio-cloud.info/blog/?p=57
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-07-11 17:49:47 UTC
Permalink
Issue #3219 has been updated by Wibowo Arindrarto.


Hi everyone,

Just as an FYI which may or may not be useful, I just stumbled on a Biopython sphinx documentation here: http://www.bio-cloud.info/Biopython/en/index.html. Its sphinx source says it was generated just about a year ago (July 2011).

The creator has a personal webpage, but it's not really clear how to contact him/her.
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
redmine
2012-07-11 18:13:40 UTC
Permalink
Issue #3219 has been updated by Peter Cock.


Seems they were interested in translating it into Chinese, based on a Google translation of this post:
http://www.bio-cloud.info/blog/?p=57
----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219

Author: Eric Talevich
Status: In Progress
Priority: Low
Assignee: Biopython Dev Mailing List
Category: Documentation
Target version:
URL:


Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
r***@redmine.open-bio.org
2016-08-03 16:12:15 UTC
Permalink
Issue #3219 has been updated by Peter Cock.

Status changed from In Progress to Resolved
% Done changed from 20 to 100

Replaced by https://github.com/biopython/biopython/issues/906 and https://github.com/biopython/biopython/issues/907

----------------------------------------
Feature #3219: Port Biopython documentation to Sphinx
https://redmine.open-bio.org/issues/3219#change-15323

* Author: Eric Talevich
* Status: Resolved
* Priority: Low
* Assignee: Biopython Dev Mailing List
* Category: Documentation
* Target version:
* URL:
----------------------------------------
Currently we use Epydoc for the API reference documentation, and LaTeX (to PDF via pdflatex, and HTML via hevea) for the tutorial. There's some material on the wiki to consider, too.

A number of Python projects, including CPython, now use Sphinx for documentation. Content is written in reStructuredText format, and can be pulled from both standalone .rst files and Python docstrings.

This offers several advantages: (i) API documentation will be prettier and easier to navigate; (ii) the Tutorial will be easier to edit for those not fluent in LaTeX; (iii) Since the API reference and Tutorial will be written in the same markup, potentially even pulling from some shared sources, it will be easier to address redundant or overlapping portions between the two, avoiding inconsistencies.

See:
http://sphinx.pocoo.org/
http://docutils.sourceforge.net/

Mailing list discussion:
http://lists.open-bio.org/pipermail/biopython-dev/2010-July/007977.html

Numpy's approach:
http://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt
--
You have received this notification because you have either subscribed to it, or are involved in it.
To change your notification preferences, please click here and login: http://redmine.open-bio.org
Loading...