A crucial division of the user's perspective and developer's perspective ought to be made.
Moreover, we have to differentiate between comments view and diffs view.
In result, we are able to split options and privileges as shown in table below:
|
User |
Developer |
| Comments view |
Allows for:
- viewing/sorting the comments,
- adding the comments/fixes,
- replying to particular comments,
- rating the comments,
- changing the view to diffs view;
|
Besides all the user privileges allows for:
- deleting/moving the comments,
- changing properties of the comments,
- exporting the comments to a file;
|
| Diffs view |
Allows for:
- browsing submitted patches and discussions about them,
- commenting submitted patches;
|
Besides all the user privileges allows for:
- deleting/committing the patches,
- setting a status for a patch,
- assigning the review to particular developer,
- viewing VCS logs;
|
The idea behind this division is that, the needs and aims of users and developers are not quite the same. My whole work have to be based on some general assumptions about these two perspectives.
Assumptions about the user's perspective are as follows:
- user loads the documentation pages to read it and he may not want to be disturbed by too tawdry comments interface,
- when user looks at the comments he is rather interested in the comments themselves, than in the diffs submitted by other users,
- in case user wants to submit a file he should be able to do so by the comment post form.
Assumptions about the developer's perspective are as follows:
- developer is rather interested in the diffs submitted by the users than their discussions,
- developer may be interested in the comments and he should be able to browse them easily and quickly,
- in case developer finds some patches useful, he should be able to commit them right from the web application.
Based on these assumptions I am able to derive the looks and functionality of comments view and diffs view.
Characteristics of the comments view are as follows:
- Sortable by: date, type, rank
- Viewable: per paragraph, per page
- Rateable for logged in users
Characteristics of the diffs view are as follows:
- Sortable by: date, status, priority
- Viewable: per paragraph, per page, per directory
At this stage I am able to propose the model of post form, which will be available under every comments or diffs view.
Fields in a post form:
- Comment (text input),
- Name (text input),
- E-mail (text input),
- Website (text input),
- I would like to submit a fix (checkbox); off by default,
- Submit comment (button). Available when submit a fix checkbox is off.
Additional fields shown when
I would like to submit a fix checkbox is
on are as follows:
- Priority (drop down list),
- Paragraph (text input) filled with paragraph's contents,
- I agree to publish my fix on a licence X (checkbox); off by default,
- Submit fix (button).
This form will be available below the comments/diffs view in case anyone would like to create a new thread or submit a patch. Moreover, every comment will have a button 'Reply' and when pressed, the post form will be provided to reply to a particular comment.
I assume that only logged-in users can post comments.
My analysis are based on a critical review of such commenting systems as these available on:
php.net
[1],
pymvpa.org
[2],
realworldhaskell.org
[3],
djangobook.com
[4] and
turbogears.org
[5].
For further discussion, please refer to this thread on the Sphinx-dev mailing list:
[GSoC] Some "web app" idea questions[6].
The core techniques resposible for serving the documentation pages to the public are still a matter of consideration. In the current state of advancement the set of tools chosen to address the appearing problems is as follows:
- Pylons[7] as a web framework,
- jQuery[8] as JavaScript library,
- jQuery[9] Form Plugin,
- Jinja2[10] as a templating system,
- Pygments[11] for syntax highlighting,
- Xapian[12] for server-side search,
- OpenID[13] for identyfing the users.
Elements of this set may change slightly before the coding period starts as this issue is still being discussed within the Sphinx's community.
I decided to rearrange the coding process in such a manner that since very early steps it will be possible to trace my progress in two ways (except of reading the code):
- by running the test suite,
- by running Sphinx itself with build web app option set.
Besides of making it easy to evaluate my work, it will mean that the framework is fully integrated with Sphinx's code base.
Detailed step-by-step description of my work is presented below. Nevertheless, I have to clarify that every piece of my work, even if it is not stated explicitly, implies writing corresponding test suites and documentation.
My progress will be described in reports written at the end of every stage (exact periods of time are specified in the Project Schedule below). Usually the reports will be presented on weekly basis.
As I plan to create a VCS abstraction framework (based on
pydocweb
[14] code)
to make it easy to configure Sphinx's interactive docs to work
with various Version Control Systems, I will also add a builtin
support for SVN
[15],
Mercurial
[16],
Git
[17] and
Bazaar
[18].
Very basic, general API premises for my project are also expressed in
Python
[19]. The purpose of this file is to present a generic
approach of my proposal even though it abstracts from Sphinx, VCSs, login
system, search engine etc.
During the summer, GSoC will be my only full-time activity.
It is very highly probable that I will pass all my exams until the end of May, thus I presume that my GSoC participation may be lower at the end of May, but I am sure that I will make up any delay at the beginning of June.
I am applying to two projects. My priority is Sphinx
[20].
The second project I am applying to is EKG
[21].