The MoinMoin wiki has to be where documentation goes to die. I've never worked with a piece of software that has such crummy docs, everything is half done etc.. It makes a strong argument towards never using a Wiki for documentation.
Anyways, here's my recipe to get HTTP Digest authentication working with MoinMoin on apache2. It wasted some of my time to get it all right, so hopefully this helps someone since the docs won't.
I recently had to put together a wiki for the RapidSMS project and one of our goals was to make the content as similar to Sphinx documentation as possible. The idea was that as certain pages on the Wiki matured, they could easily be rolled into the official Sphinx docs, all without changing the actual format.
MoinMoin 1.9.3 actually supports Restructured Text as a markup, the same format as Sphinx, and it also support Pygments to do syntax highlighting, also the same as Sphinx, but the two didn't play well together: although you could create pages using RST, Pygments would not highlight code segments in them.
So I hacked on MoinMoin a bit to make it work. It isn't the prettiest of patches, but they rarely are. Here's a ReST page with some highlighting:
The next problem was that I wanted a slightly better editor for RST. I've used CodeMirror in the past and always thought it struck a nice balance of performance and functionality. Sadly, there wasn't an RST parser written for CodeMirror, so I threw a very rough one together.
More ugly MoinMoin hacking let me insert it as the default editor. MoinMoin really, really needs to adopt a templating language, it is especially ridiculous for me to edit a .py file to add some javascript. In any case, here's the editor:
You can choose to add just the Pygments highlighting to ReST or to also include the CodeMirror editor, up to you. Grab the gist and check out the README for installation instructions. It is slightly laborious, but mostly just copying files around. Hope you find it useful. You can check out the version we have running on the RapidSMS wiki.
As I've detailed before, our internet here in Rwanda can be a bit flakey. As such, it is pretty useful having documentation for the libraries we use available when the network is down. (or when it is just really slow, which is often)
I used to use the HTML version of the Sphinx docs for Python and Django, but discovered CHM (Compiled HTML) the other day and it has even better search capabilities. On OS X the best CHM client I've found is ArchMoch, though there seem to be some files it doesn't get along with.
Anyways, to save you the time of tracking all those CHM files down, here they are hosted off my DropBox:
Note that the JQuery CHM doesn't seem to have an index built for it, so searching isn't quite as great for it.
I haven't found a good CSS reference in CHM format, my ideal would be something like the sitepoint or w3schools references. Maybe if I get the time I'll compile one later. But I did find a nice little cheatsheet for CSS:
Of course, even having these you won't get the full power of Google's amazing answering powers, but it is something. If you have any to add, let me know and I'll link them up.
A few days ago, some articles appeared in the New Times and the Rwandaise, boasting about how Rwanda has the fastest internet speeds in the region, and the third fastest in Africa, beating even South Africa. The articles used the recent results posted by Ookla as a reference, which does indeed show Rwanda as 89th in the world, with download speeds of 2.36Mb/s.
Now for anyone in Rwanda, this probably seemed a bit surprising. I have an unhealthy obsession with bandwidth, so I know first hand that we get nowhere near 2 Mb/s, that much is clear every single day as I go about my work at Nyaruka.
So what explains the discrepancy? Is Ookla wrong?
The answer lies in how sites like speedtest.net came about and what they are trying to measure.
Ten years ago, DSL and Cable were just starting to make their presence in the United States. There was fierce competition from various providers on pricing and claimed bandwidth, but few ways for consumers to judge how fast their service really was. To address that need, sites like dslreports.com and speedtest.net came about. Their goal was to measure the speed of the DSL and Cable connections.
The way these sites work is quite simple. Speedtest.net gets various internet providers to host a large file on one of their servers. Then you and I go and try to download the file, timing how long it takes, this is what is happening when you are measuring the bandwidth using the speedtest client. They divide the size of the file by how long it takes and you have a rough approximation of your bandwidth speed.
Now in order to accurately measure the speed of only the DSL or Cable portion of the connection, you need to have the shortest path to the test file you download. Speedtest.net has done a good job of getting these files hosted on various servers across the world. And one of those places happens to be the Rwandatel offices in Kigali. This is where the validity of the tests gets into trouble.
A diagram might help explain.
This diagram gives a simple view of what a typical set up might be in America, in this case Atlanta, Georgia, where one of my friends Joe George lives. (more on him later) The green arrow represents his connection to his internet service provider (ISP). In his case, he's using cable, which gets about 10Mb/s. Since his ISP is also a speedtest.net test site, when he tests his connection, he is testing his cable connection only. Speedtest.net is NOT testing how fast he can access the rest of the internet, only the connection between his computer and his ISP.
That is valid, because his internet provider has a far far faster connection to the internet. The purple arrow represents that, the connection between the ISP and the rest of the internet. In Atlanta, that is fiber, probably multiple fiber optic lines from different providers, incredibly fast and reliable. So the bottleneck for Joe is almost always going to be his connection to the ISP, the green arrow, not his ISP's connection to the internet (the purple arrow).
Ok, so now let's take a look at the same situation in Rwanda.
Rwanda has a pretty great network internally. We have a fantastic 3G network from three different providers, at reasonable rates, which makes getting a connection quite accessible. But what we don't have, is a great connection to the internet.
Here, the green arrow represents a typical 3G modem, which tops out about 2.5Mb/s in practice. That's fast, and you'll notice that's also about the speed that Ookla says our internet is. The reason for that is that Rwandatel has a server based in Kigali that is a speedtest.net testing site. So when you go to speedtest.net and pick Kigali as your testing location, you are actually testing the green arrow only, how fast your internet is to the Rwandatel server in Kigali.
That works fine in the case of Joe, where the ISP's connection to the internet is far far faster, but it doesn't work in Rwanda. Our ISP's connection to the internet is still very slow, either going over satellite or microwave, the purple arrows here. So although we can reach our ISP very quickly, as soon as we try to reach the rest of the world, the rest of the internet, then our speeds slow down to a crawl.
This is pretty easy to test in practice, you just need to change which site you are testing against when you go to speedtest.net. Yesterday evening I did just that using my Rwandatel connection and here were the results.
Kigali to Kigali: 2.12 Mb/s
Kigali to Kampala: 0.11 Mb/s
Kigali to Atlanta: 0.09 Mb/s
So we see there that yes, our connection to Rwandatel is indeed very fast, but as soon as we try to leave Kigali, it slows down to a crawl. That's because the connections from Rwanda to the world are still very, very slow despite our great internal network.
We can validate this by going in the opposite direction. Remember Joe? Well I asked him to use his crazy fast internet to test against the same sites, here's what he got:
Atlanta to Atlanta: 10.01 Mb/s
Atlanta to Kampala: 1.15 Mb/s
Atlanta to Kigali: 0.10 Mb/s
Here we see that in Kampala, while their ISP's do not provide quite as quick of an internet connection on average (the green arrow), their connection to the rest of the world, the internet at large, is much faster than Rwanda's. So although Ookla, which measures the green arrow, says they are slower in some cases, that is actually incorrect in practice.
The silver lining with all this is that backbones are on the way, and once hooked up and given they have sufficient capacity, those claims made by Ookla may actually become true. Our bottleneck is our provider's connection to the internet, so once that is fixed we will indeed have much, much, faster internet.
You can actually get a taste of that if you use the internet at unusual hours, like 2AM. At that time of the day, there aren't enough users to saturate the connections Rwanda does have, so the speed is great. But we need the fiber to be hooked up before we can honestly claim to have fast internet. That's a day I'm looking forward to, hope it happens soon.
PS. In the interest of verification, here are all the internet speed test results we used for this article
Git submodules are a convenient way to create a dependency on another git project. This can be useful if you depend on another project and want to make it easy for others to get your system up and running.
I won't cover creating submodules here as that is pretty well convered in the git manual, but updating them is slightly less obvious. When creating submodule dependencies, git actually saves a reference to the version of the tree at that point in time. That's a good thing, it prevents things from breaking due to your dependency changing out from under you. But there are times when you'll want to update that reference. The trick is to realize that git is keeping a reference to whatever version of the git tree is currently checked out. So all you need to do is go and pull the submodule, then commit the project as a whole.
That should do it. I'm still coming to terms whether I like this particular style of dependencies, for those of us with limited bandwidth it does cause rather large repositories to be sent over the wire just to get things running. Having dependencies be managed via PiPi in Python is certainly the better option if possible.
