This is a plugin for the excellent Tomboy note taking application. This plugin allows you to quickly determine the number of lines, words, and characters in your note, much like the Unix wc command. Like Tomboy, this plugin is written in C# and runs on Mono.

Screenshot

Sphinx is used for Python documentation (compare old vs. new), but it is great for for any project in any language. Integrated wikis (like Trac) are nice; but I prefer to keep the documentation together with the source code. Sphinx is perfect for that. It also looks like a million bucks.

This document was tested on Fedora 8; however it is likely to work on all platforms that Python supports. Please contact me if you have questions or comments.

Getting Started

First, see the Sphinx documentation and get familiar with installing it (easy_install), initializing a project (sphinx-quickstart), and building your standalone HTML docs (make html).

Notice how (as of right now), the templating documentation is suspiciously missing? That is what this document covers. I spoke with Georg Brandi briefly over email and he said that the document is forthcoming. Therefore I will try to make this page here have a how-to style so that it will hopefully complement the official Sphinx docs when they come out.

The Basics

First, read up on the Django-like Jinja templating system, to get a basic feel for how things work. Just scan through it because you can learn more quickly by experimenting with your own templates.

Your Sphinx templates go in a special subdirectory of your documentation source. By default, this is .templates, so we will use that. (It is set in the templates_path directory in conf.py.) Therefore, all of your template files will go in source/.templates.

Templating with Jinja is all about extending (or inheriting) previously-made templates. So the procedure is to make your own template file and say “this file is mostly like such-and-such template, with these differences….”

Sphinx uses the following built-in template files to generate HTML pages:

• genindex.html
• index.html
• layout.html (This is the main one you want to modify)
• macros.html
• modindex.html
• page.html
• search.html

Making a Template

To modify a template, choose a filename of the template you want to modify and create a file with the same name in .templates. Go ahead! Create .templates/layout.html with some simple content:

{# Filename: .templates/layout.html #}
This is the new layout!

Now run make html to rebuild the HTML. (Note, for Sphinx versions before 0.1.61945, you must run make clean.) Your documentation is gone, but at least you successfully overrode the old layout template!

Extending a Template

We see that you can make a new layout.html to completely override the old layout.html, but how do you merely modify one small part of it? To change just one part of the original Sphinx template, make a new template that extends the old one, and then put a block in your new file. (If you don’t know about extending and blocks, see the Jinja web page.)

Warning: You may try to make a new layout.html that extends the old layout.html. That is wrong:

{# XXX This is wrong! XXX #}
{# Filename: .templates/layout.html #}
{% extends ‘layout.html’ }

If you don’t believe me, try it! It will cause an infinite loop when layout.html tries to extend itself. Instead, you must use a Sphinx-specific extension to Jinja by prepending the ! character to the template filename:

{# This is just fine #}
{# Filename: .templates/layout.html #}
{ extends ’!layout.html’ }

That’s it! Now you can go crazy making your own blocks that override the old layout template. For example:

{# Filename: .templates/layout.html #}
{ extends ’!layout.html’ }

{ block afterfooter }
Hi!  I am beneath the footer.
{ endblock }

Useful Blocks to Create

Here are some blocks (all in layout.html) that you should start extending. As of this writing, all of these blocks are completely empty in the original layout, so you are not replacing anything, only adding your own content. Therefore they are a good place to experiment.

• extrahead
• beforerelbar, afterrelbar
• beforesidebar1, sidebar1, aftersidebar1
• beforedocument, afterdocument
• beforesidebar2, aftersidebar2
• beforefooter, afterfooter

How To: Add Your Own CSS Stylesheet

To add your own CSS stylesheet, for example, mystyle.css, first create the file in the .static directory. Next, you have a choice depending on what you want to do:

• To use your styles in addition to the defaults, add an “extrahead” block in your own layout.html template, like so:

  {# Filename: .templates/layout.html #}
  { extends ’!layout.html’ }
  
  { block extrahead }
  
  { endblock }
  

• To completely replace the old styles, replace the html_style variable in conf.py and set it to “mystyle.css”. Of course, you can use @import other styles or do anything else that CSS supports.

How To: Change the “root” page name

I don’t like the default text in the upper-left side of the page. It just says “ProjectName vX.Y documentation” which is pretty boring. To replace it, override the “rootrellink” block in your own template. Here is what I use:

{# Filename: .templates/layout.html #}
{ extends ’!layout.html’ }

{ block rootrellink }

  FooProject (v{{ release }})
  »
  

{ endblock }

How To: Show the current page name in the top navigation bar

I like to show the current page name in the top part of the page, because it provides a kind of “you are here” feel. For example: FooProject » Getting Started » Compiling and Installing

Well, Sphinx builds this for you automatically, except it takes the liberty of deleting the current page from the end of the list! I have no idea why they don’t make it optional, but they just mercilessly chop off the last page from the ancestry list. Here is how you can add it back using templates:

{# Filename: .templates/layout.html #}
{ extends ’!layout.html’ }

{ block relbaritems }
  { if current_page_name != ‘index’ }
{{ title }}

  { endif }
{ endblock }

How To: Extra Sidebar Content

I like to put extra stuff in the sidebar for every page, however maintaining the html_sidebars variable is tedious. To ensure that every page loads your custom HTML in the sidebar, first create .static/mysidebarcontent.html page with something in it. (Note this file goes in .static, not .templates.)

Next, put this in your layout.html:

{# Filename: .templates/layout.html #}
{ extends ’!layout.html’ }

{ set customsidebar = ‘mysidebarcontent.html’ %}

I know it’s kludgy but it works. You may also want to consider doing this in page.html if you don’t want the custom sidebar stuff on the special index, module index, etc. pages.

Final Comments

Here are some final notes that I have accumulated in no particular order:

• Searching seems to work only if you include the document source. So make sure you set html_copy_source to True in conf.py.
• html_index is not quite intuitive. It does not simply set the Jinja template to use for the index, but rather it activates special handling for the index page. Without it, the index page will build normally using page.html (which extends layout.html). But if you set html_index = “foo.html” for example, then the prefab index.html will run which loads your foo.html inside it in the body (as the indextemplate variable). So remember, index.html is not used unless you set html_index; and if you do set html_index, then your template will merely be rendered as part of the document body. In summary:
  • If you want the index page to render using the same template as all the other pages, then you must not set html_index.
  • If you want to activate the special template for the index page, you must set html_index in conf.py. The file that you specify will be included in the template.
  • If you want to activate the special template and you want to completely override index.html, you must set html_index in conf.py and also create your own index.html in .templates. You will probably want to “extends ‘layout.html’” too. The “indextemplate” variable will be set to whatever you specified in conf.py. To actually render the contents of that file, you must

    {{ rendertemplate(indextemplate) }}

    somewhere in your index.html template.

Contents

1. Objectives
2. Preparation
3. Enabling the Environment
4. Mono 1.9
5. Libgdiplus
6. GTK#
7. Mono.Addins
8. Monodoc
9. Mono Tools
10. Gtksourceview
11. MonoDevelop
12. Nant
13. Finish

Objectives

• MonoDevelop platform ready to use on CentOS 5 or Fedora 8
• For minimal maintenance headache, use the base operating system to provide as much sofware as possible, with the obvious exception of Mono 1.9 and MonoDevelop 1.0
• The install is isolated from the rest of the system. MonoDevelop and its dependencies should have no overlap or interference with the base operating system.

Preparation

• Note: In this document, all source code will go in /usr/src/monodevelop-install. All installed packages will go in /usr/local/software.

• mkdir -p /usr/local/software/mono-1.9

• sudo chown -R `whoami` /usr/local/software # (Be careful if you already have software here)

• mkdir -p /usr/src/monodevelop-install
  

• yum install glib2-devel pango-devel gtk2-devel glade2-devel libgnome-devel \
              gnome-desktop-devel gnome-panel-devel libgnomeprintui22-devel  \
              gtksourceview-devel ruby ruby-rdoc gtkhtml38-devel wget        \
              # (maybe openssl-devel also)
  

• echo 'PATH="/usr/local/software/mono-1.9/bin:$PATH"' \
       > /usr/local/software/mono-1.9/env.sh
  

• echo 'export PKG_CONFIG_PATH=/usr/local/software/mono-1.9/lib/pkgconfig' \
       >> /usr/local/software/mono-1.9/env.sh
  

• echo 'export LD_LIBRARY_PATH=/usr/local/software/mono-1.9/lib' \
       >> /usr/local/software/mono-1.9/env.sh
  

Enabling the Environment

Important: You must always run this command before using Monodevelop, and also before continuing on with this procedure.

source /usr/local/software/mono-1.9/env.sh

In this document, Monodevelop is not completely integrated into the GUI, menus, etc. for a couple of reasons:

1. Getting Monodevelop to show up in the menus is somewhat distro-specific. For RPM-based distros, look into setting the $XDG_DATA_DIRS variable in /etc/X11/xinit/xinitrc.d/, but you will also have to get the path working. For Debian-based distros, look into doing the same thing in /etc/X11/Xsession.d. And if you happen to be trying this on Solaris, look into /usr/dt/config/Xsession.d. Oh and by the way, the .desktop file that ships with Monodevelop is invalid for my Fedora 8 system! So you will have to manually edit it and (IIRC) remove the TryExec line.
2. As you can see, this requires a bit of mucking with “standard” package-maintained config files, which I am hesitant to do because it violates the objective of isolation.

All this means you will always have to first source the small shell script which sets up the correct environment variables whenever you want to run Monodevelop.

Mono 1.9

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/mono/mono-1.9.tar.bz2

• tar xjf mono-1.9.tar.bz2

• cd mono-1.9

• ./configure—prefix=/usr/local/software/mono-1.9

  • Optionally,

    —with-ikvm-native=no—with-moonlight=no

  • Optionally,

    —with-xen_opt=yes

• make && make install

Libgdiplus:

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/libgdiplus/libgdiplus-1.9.tar.bz2

• tar xjf libgdiplus-1.9.tar.bz2

• cd libgdiplus-1.9

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

GTK#

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/gtk-sharp-2.0/gtk-sharp-2.8.4.tar.bz2

• tar xjf gtk-sharp-2.8.4.tar.bz2

• cd gtk-sharp-2.8.4

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

Mono.Addins:

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/mono-addins/mono-addins-0.3.1.tar.bz2

• tar xjf mono-addins-0.3.1.tar.bz2

• cd mono-addins-0.3.1

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

Monodoc

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/monodoc/monodoc-1.9.zip

• unzip monodoc-1.9.zip

• cd monodoc-1.9

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

Mono Tools:

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/mono-tools/mono-tools-1.9.tar.bz2

• tar xjf mono-tools-1.9.tar.bz2

• cd mono-tools-1.9

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

Gtksourceview:

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/gtksourceview-sharp-2.0/gtksourceview-sharp-2.0-0.10.tar.gz

• tar xzf gtksourceview-sharp-2.0-0.10.tar.gz

• cd gtksourceview-sharp-2.0-0.10

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

Monodevelop:

• cd /usr/src/monodevelop-install

• wget http://go-mono.com/sources/monodevelop/monodevelop-1.0.tar.bz2

• tar xjf monodevelop-1.0.tar.bz2

• cd monodevelop-1.0

• ./configure—prefix=/usr/local/software/mono-1.9

• make && make install

NAnt

This is optional, but many .NET applications build with it, so it might be worth throwing in there.

• cd /usr/src/monodevelop-install

• wget http://downloads.sourceforge.net/nant/nant-0.85-bin.tar.gz

• tar xzf nant-0.85-bin.tar.gz -C /usr/local/software/mono-1.9

• echo ’#!/bin/bash’ > /usr/local/software/mono-1.9/bin/nant

• echo ‘mono /usr/local/software/mono-1.9/nant-0.85/bin/NAnt.exe ”$@”’ >> /usr/local/software/mono-1.9/bin/nant

• chmod +x /usr/local/software/mono-1.9/bin/nant

Finished!

You’re done! Run it!

monodevelop

Feel free to contact me if you have any input to add. I will try to add another post for Debian/Ubuntu and possibly Solaris in the future.

This is a plugin for the Bazaar source code control system. It will pop up a small window when pushes and pulls have completed. This way, you do not need to wait around watching (slow) transactions over the network. Here is a screenshot of bzr_notification in action:

View the slides in HTML format: Making Magic with SSH

You can also get the text source file, or download everything in zip format.

I will post slides of my SSH talk shortly. Please check the site in a day or so, or subscribe to the RSS feed.

About the Siam eBook Printers giveaway, I will be contacting the winners of the lucky draw shortly.

So stop by and say “This is awesome!” (or even better: your own constructive criticism) to get your discount today! As always, shipping is free, and books about free software (and open source) get an additional 150 baht price reduction.

For now, there is only a simple Greasemonkey script for an excellent free software-related web site.

If you have an ebook in PDF format, just attach the file on the web page and provide your delivery address. In a few days, a nice bound volume arrives at your door from EMS. If you’ve ever seen these shops in malls and universities that print and bind books, then you know exactly what this is, except we do it over the web.

We are aiming directly at foreigners and I.T. professionals in Thailand. Here is what makes Siam Book Printers unique:

• Everything is in English
• We cater to busy people. You attach a PDF on the web site, and you receive EMS packages.
• We guarantee no mechanical errors, smudges, missing pages, or other flaws. If you are dissatisfied, we will send you a replacement book.
• There is no guesswork; you preview exactly what you will get.
• Besides standard bank transfers, we accept credit card payments and PayPal. We accept payment in Thai baht or U.S. dollars.

Personally, having eBooks printed is one of my favorite activities in Thailand. When done right, the end result is quite beautiful. Ever since I had The Debian System from No Starch Press made into a hardback, I have been hooked. I doubt the site will be successful financially; but my goal is to reveal and simplify the eBook printing process to more foreigners and software professionals.

Finally, Siam Book Printers is a platform to promote free software in Thailand. We offer discounts for eBooks about free and open source software. When you order a book about free or open source software, just click the checkbox to receive your discount!