jacobmason.us

Midterms are long past, and it’s been far too long since I’ve updated my blog, so here it goes. I’ve been keeping busy working on sphinx-web-support and the sphinx-demo-webapp. At this point both are working, and I believe all features have been implemented.

Since the last post I’ve added the ability to propose changes to documentation when making a comment. When a user makes a proposal there will be a “proposal” link below their comment. When clicked a pretty diff of the original source and their proposal will be displayed.

Users that are logged in will now also have the option to delete comments that they have made. Alongside this, a system for comment moderation has also been added. When a comment is added the API user has the option of marking the comment as displayed or not displayed (displayed is default). Comments that are not displayed won’t be shown to regular or anonymous users. When a moderator views an undisplayed comment they will have the option to either accept or reject the comment. Moderator’s also have the ability to delete any comments that are already displayed.

Pencils down date is now less than a week away, so for the next few days I’ll be working on a few final details such as enabling comments on code blocks, writing a nice tutorial, and making the authentication page easier to use.

After a week and a half of work I’ve finally gotten the comment system to a working state. The default backend uses SQLAlchemy to store comments and votes, but this can be extended to use other storage systems.

On the front end I’ve created a jQuery script to deal with comments. This turned out to be the most challenging part of the comment system, primarily because of my lack of experience with jQuery/javascript. While I’ve used jQuery successfully in the past, I’ve never taken on a project of this magnitude. In the process of creating the script I’ve been through several designs, and finally found something I think works. I’ve learned a great deal about javascript, and for the first time feel like I have a solid grasp of jQuery and the general patterns that should be used with it. The current script allows users to add comments, reply to comments, vote on comments, and sort the comments. All communication with the server is done via AJAX using json.

There are still a few features left to implement, namely a way to delete comments, and cross browser compatibility testing. So in the next week I’ll be tying up the loose ends in the comment system, as well as add a way for user’s to suggest changes to the documentation. After that all that is left to do is handle the merging of comments when documentation is updated, and the project will be complete.

That’s all for now, I better get back to coding!

It’s been a busy couple of weeks, but I’ve finally finished moving and am turning my full attention back to the project. To get the week started I added sidebars and relbars to the context dict that is returned by the api. While primarily aesthetic, it does make the demo look quite a bit more complete.

After that I turned my attention to serve side search, which is now fully functional . There are currently two search engines that can be used: Xapian, and Whoosh. Xapian is written in C++ and is quite fast, while Whoosh is implemented in pure Python. The best way to learn about the new features is to check out the Web Support Quickstart.

I’ve put up a demo app that utilizes the web support package. It doesn’t do much yet, but it’s possible to see where comments would be anchored in a document. You can check it out here.

The first week of coding has come to an end, and it was just as busy as expected. I spent the first part of the week in Kansas, where it turns out I will be moving in the middle of June. The end of the week provided more time to code though, and the good news is I’ve made my first commit!

At this point the web support package has the ability to build a set of Sphinx documents and provides a simple API that a webapp can use to access the documents and display them. I’ve create a simple Flask webapp that demonstrates the (limited) functionality of the package. In the future I hope to host the application so that everyone can easily see the progress. For now to try it out you’ll have to download the sphinx-demo-webapp. To get things working you’ll need to set a couple paths in sphinxdemo/conf.py:

DOCTREE_ROOT = '/your/doctree/root/'
OUTPUT_DIR = '/your/output/directory/'

DOCTREE_ROOT should be a directory of reStructuredText files that has a conf.py file created by sphinx-quickstart. OUTPUT_DIR is the directory that output files will be written to.

You can then run the Flask application:

$ python application.py
 * Running on http://127.0.0.1:5000/
 * Restarting with reloader...

You can then go to “http:127.0.0.1:5000/build” in your browser and the app will build the documentation (of course you would never do this in a real application). The documentation can then be viewed by going to “http://127.0.0.1:5000/docs/<docname>” where <docname> is the name of the document you wish to view. For example, to view the page generated by index.rst use the url “http://127.0.0.1:5000/docs/index”.

There are still several things that need to be done with the builder and translator. After that it will be time to get started on server side search. My goal is to get ahead of schedule before moving since that is going to take out a good chunk of my time.

The final week of the “bonding period” is coming to an end, so it’s time for another progress report. The first part of the week was again spent reading code/documentation. I’m now familiar with Flask and  have started writing a small demo application that will utilize the web support package. I’ve  also just started writing code for the web support package that will perform an initial build of documentation sources.

The official coding period starts next Monday, and since I’ll likely be moving in the near future the next few weeks promise to be a busy time! There should still be plenty of time to code though.

Happy coding all!

It’s been another week, so it’s time for another blog post. I’ve spent more time reading the Sphinx source, and also spent some time reading the docutils documentation. Hopefully soon there will be something more interesting to blog about.

Since this is the last week of my senior year at UNK I’ve kept quite busy with things other than my GSOC project. I have had some time to begin reading the Sphinx code, and next week I should be able to start seriously planning how the Sphinx Web Support package will work.

I must say, after working primarily with Java for the last few months it is quite nice to be using Python again .

This is my new blog that I will use to keep the world updated on my GSOC project. I’ll be spending the next month getting to know my mentor and the other folks at Pocoo, as well as familiarizing myself with the Sphinx codebase.

To learn more about my project take a look at my GSOC application. If you have other suggestions feel free to leave a comment or catch me on IRC. I’ll be hanging around #pocoo on irc.freenode.net, just look for jmason.