Hello, I am planning on applying to GSoC to port Sphinx to Python 3 and integrate sphinx.web(last year's GSoC project) into Sphinx. Basically these are two projects but Georg pointed out that just one of the two is probably too short for the GSoC.
As proposed by the Wiki i would like to get some feedback on the first draft
of my proposal.
However currently i have now idea how to handle the timeline as there is no
way of knowing what issues occur during the project, so a timeline is not
included in my proposal. I would be grateful if anybody could point me into
the right direction there because a timeline seems to be expected for every
project.
-- Daniel Neuhäuser
====================================================================
GSoC 2010 Sphinx: Port to Python 3.x and Integration of `sphinx.web`
====================================================================
:Last change: Monday March 30 16:09:16 CEST 2010
:Status: Draft
.. contents:: Table of Contents
Abstract
--------
Beginning with the `Python Documentation`_ Sphinx_ managed to become the
documentation generator for python projects, however as of now Sphinx requires
Python_ 2.x to run, although 3.0 was released on the 3 December 2008 [1]_. Not
being able to run Sphinx_ with Python_ 3.x is a major issue for a lot of
projects planning to switch.
Therefore the first part of my proposal is to port Sphinx_ to Python_ 3.x to
resolve this issue and hopefully help more projects to make the change to 3.x
The second part of my proposal is to pick up `sphinx.web`, the Google Summer
of
Code project from last year [2]_ and integrate it into Sphinx_ which has not
yet been accomplished. This is important in order to be able to involve a
project's community into the development process of a documentation, to
improve
the user experience of the `Python Documentation`_ and to further establish
Sphinx_.
Implementation
--------------
Port to 3.x
^^^^^^^^^^^
Branching Sphinx_ and porting it to 3.x manually takes a lot of work in itself
and requires maintenance of two different branches. Although this is should be
possible to handle it the goal should be to avoid it. Instead we use the tools
introduced with Python 2.6:
`python -3`_
Starting the python interpreter with the `-3` option enables warnings
about incompatibilities to Python 3.x which cannot fixed using
2to3_.
Running the test suite using this option should warn us about every
serious problem which could occur later, these should be fixed
manually
as far as possible and pushed to the main branch as soon as possible,
keeping the differences between the code created during this project
and the Sphinx_ code as small as possible.
2to3_
2to3_ is a tool introduced with Python_ 2.6 which allows automatic
transformation of Python_ 2.x code to Python_ 3.x.
The transformation process is done using so called `fixers` which are
responsible for the transformations for specified cases. The standard
library and therefore 2to3_ already provides a set of fixers_ which
handle almost all code however we might need to provide our own.
Jinja2_ one of Sphinx_'s dependencies does the latter.
The porting will be done in tree steps:
1. Checking if the test suite has full code coverage and if not extending the
test suite to reach that goal.
2. Run the test suite with `python -3` to find and fix incompatibilities as
described above. As much as possible of this work should be done in the
main
branch.
3. Integrate 2to3_, using the techniques described above and merge everything
into the main branch.
Integration of `sphinx.web`
^^^^^^^^^^^^^^^^^^^^^^^^^^^
The current implementation of `sphinx.web` needs to be merged with the main
branch. As the latest change was made on the 19 august 2009 it might be
necessary to make some changes to get it working and make it possible to port
it with 2to3_ which will then be a requirement.
Once this is done `sphinx.web` should be pushed to the main repository.
However
it is to be expected that improvements have to be made to get it accepted.
About me
--------
My name is Daniel Neuhäuser, i am 18 years old and currently in the eleventh
grade of the `Bergstadt Gymnasium Lüdenscheid`_.
I started programming with Python_, as my first language, in May 2008 and have
been experimenting with a couple of other languages since then [3]_. I teached
myself software development and consider myself an active member of the german
and english speaking Python_ community.
My interested lies in the development of web applications, in the future i
intend to learn more about parser and compiler techniques.
I think of GSoC_ as a way to learn management and communication in software
and
especially FOSS projects. I hope to be able to get faster and more involvement
in FOSS projects with the knowledge gained during the summer.
Contact
-------
:E-Mail: dasdas...@gmail.com
:IRC: DasIch in irc://irc.freenode.net:6667
:Twitter: `...@dasich <http://twitter.com/DasIch/>`_
:Phone: Will be given by request if necessary.
.. [1] See also http://python.org/download/releases/3.0/
.. [2] Proposal
http://tosh.pl/gminick/gsoc/sphinx/
Implementation
sphinx.web_
.. [3] JavaScript, Scheme, Haskell and Ruby
.. _Python Documentation: http://docs.python.org/
.. _Sphinx: http://sphinx.pocoo.org/
.. _Python: http://python.org/
.. _Bergstadt Gymnasium Lüdenscheid: http://bergstadt-gymnasium.de/
.. _GSoc: http://code.google.com/soc/
.. _2to3: http://docs.python.org/library/2to3.html
.. _python -3: http://docs.python.org/using/cmdline.html#miscellaneous-options
.. _fixers: http://docs.python.org/library/2to3.html#fixers
.. _Jinja2: http://jinja.pocoo.org/2/
.. _sphinx.web: http://bitbucket.org/gminick/sphinx-gsoc2009
signature.asc
Description: This is a digitally signed message part.
