Hello again,
I decided to drop the timeline thing and just define some milestones i
want to
achieve during the project and changed the proposal. Here is the
complete,
changed proposal:
====================================================================
GSoC 2010 Sphinx: Port to Python 3.x and Integration of `sphinx.web`
====================================================================
:Last change: Friday April 2 13:24:36 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.
Milestones
----------
As I'm not planning to create something entirely new with this project
making
a
timeline is hard. Instead I will set a couple of milestones for the
subprojects
I want to fullfil during the project. Issues which arise during the
course of
this project get assigned to these milestones and will be documented
in a
public bugtracker. This way not only my mentor but everyone will be
able to
see
and follow the progress at any time.
Additionally I will publish a weekly report in which i summarize new
and
resolved issues, to give people a chance to follow the progress more
easily.
This could be done with a blog or with a mail to the sphinx-dev_
mailinglist.
Milestones for `Port to 3.x`_:
1. Document every warning raised by running the test suite with
`python
-3`
as an issue.
2. Removal of Incompatibilities: Every warning documented should
be
removed
as long as we don't need to use a 2to3_ custom fixer.
3. Integration of 2to3_: Use 2to3_ to translate Sphinx_ during the
installation process and add custom fixers as necessary.
Milestons for `Integration of sphinx.web`_:
1. Merge: Merge `sphinx.web` with the main branch and make the
test suite
pass.
2. Improve: Make required improvements and changes required to get
it into
the main branch.
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`_. It is to be expected
that
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: [email protected]
: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/
.. _sphinx-dev: http://groups.google.com/group/sphinx-dev/
--
You received this message because you are subscribed to the Google Groups
"sphinx-dev" group.
To post to this group, send email to [email protected].
To unsubscribe from this group, send email to
[email protected].
For more options, visit this group at
http://groups.google.com/group/sphinx-dev?hl=en.
