Loslassa 0.3.3

A simple way to interactively develop web pages with reStructuredText and love :)

Huboard issues

Loslassa

This is a little project to help my family create web pages.

Besides from that it serves mainly as a playground for me to explore new concepts and technologies.

Characteristics

Works everywhere (where Vagrant with VirtualBox works)

Easy to administrate - Completely self contained in a vagrant box

Easy to install - Just run vagrant up in project folder (with vagrant and VirtualBox installed)

Contains examples to get started - Have a look in projects/examples

Offers a short feedback loop - Page will be committed and rebuild on every save

Gives helpful error messages - Courtesy of Sphinx

Easy publishing - Run git push and it will be deployed via githook (needs some setup on the remote end)

Basic ingredients

ReStructuredText

From the reStructuredText homepage:

reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains.

As the description says: useful for simple web pages - if it gets more involved you need a bit more, which in this case will be provided by the sphinx documentation generator.

Sphinx Porcelain

My favorite way to create documentation for Python projects is with sphinx. It works quite comfortable already and can create nice static web pages with theming support and it is easily extendable.

The documentation is generated by creating a tree of reStructuredText files representing the structure of the generated document. Navigation, cross references and search index are all generated from the structure and light markup in the actual files. This is solving a major problem of generating web pages already so that one does not have to worry about these things anymore.

What is important for me: the actual content is cleanly separated from the layout and design aspects and is kept in simple text files. If one ever decides to move to a different system it is not too painful to adjust the document tree to the new system, as the markup can be removed/transformed easily.

Why porcelain?

Sphinx is very powerful and provides the possibility to generate your documentation as PDF, HTML, Man-Page and whatnot. Even creating a new sphinx project with sphinx-quickstart, would leave a novice with a lot of stuff to cope with. I can’t see my people suffer through this without several nervous breakdowns. So the first idea is to just add some porcelain to the plumbing of sphinx and create a simple example project to get them going.

Git porcelain porcelain

Git is a fantastic DVCS-System that can be abused in many ways. I plan to abuse it as an automatic backup system and publishing tool for the web pages.

Problem is, that even the git porcelain isn’t anything I can let members of my family let loose on, so the aim here is to abstract git away completely and use it under the hood for rollback functionality and publishing content.

Love

I love my family and open source software, so this is the perfect excuse for me to combine both and create an orgy of love that gives something back to the OSS-community, helps my family to do their thing and helps me not having to figure out whatever terrible tools they might be using to create their websites with, when they run into problems - I rather help them loslassing :)

My expressions of love might differ from other people, but in relation to Loslassa they are as described below …

Development Server

I understand the attraction of all these colorful WYSIWYG interfaces that make you feel that creating a nice web page is really easy and just a few clicks away. But you might as well be left with something that is not really what you wanted, hard to maintain and hard to get away from.

So I hope I can get my folks to adopt the Loslassa way - only problem is: Loslassa is definitely not WYSIWYG but rather WYGIWYWIYWTLSN (What You Get Is What You Want If You’re Willing To Learn Something New) so I need something to lure them into believing that this might be usable.

As seeing is believing an integral part of Loslassa is a simple reloading development server based on code from Werkzeug. This makes sure, that a fresh version (as in: the current state of the project files on the hard disk) of the web page you’re working on is displayed in the web browser.

The server simply watches the Loslassa Project Directory (TM) for file changes, rebuilds the pages and reloads itself. In a later version this server will also be taking care of the version control side of things, by keeping the git repo up to date. Publishing the page will then be a simple git push to the web space.

Friendly command line interface

My current experience with programming lies mainly in the backend. In my day job I develop an in-house distributed system for a german Antivirus company and we don’t bother with fancy GUIs - we have extensive APIs and simple web interfaces (thanks to Flask) where sensible - Desktop GUI is just not on my map at the moment. But everybody loves the command line, don’t they ;)

Anyway … a way to write CLIs in a pythonic way is Plumbum which I just started playing with and I don’t think I will ever go back to argparse. Another aspect of the plumbum approach is the handling of paths, which features an overloaeded / operator for path concatenation and methods directly on the path object. I started using this in the code and it’s quite nice …

Extension of Love

My life would be much poorer without open source software, so even if you’re not a member of my family: if you want to use this or parts of it, go ahead - it’s BSD Licensed. If you have an idea how to make it better or want to contribute something (code, examples, whatever), feel free to contact me, open an issue or send me a pull request.

About the name

Loslassa or los lassa means to let go and relax in a german dialect called Swabian spoken in parts of South Germany. As I moved into this part of Germany in 2011 I came in direct contact with this dialect and I am still quite in awe of it, but I really like it … or at least I am really trying very hard to like it - so I thought I give my first open source project a Swabian name.

Anyway, when I came up with the idea to this project I went to my Yoga class and my Swabian Yoga teacher always says “loslassa, loslassa, loslassa” whenever she wants us to relax after some contortion she made us go through - so this is my favorite part of the lessons (fun fact: the path to the main file in the loslassa sourcecode is loslassa/loslassa/loslassa.py).

So in the true spirit of Loslassa I hope this little project helps you let go of your preconceptions how web pages have to be created and you try the Loslassa way ;).

Inspiration

README driven development:

• http://tom.preston-werner.com/2010/08/23/readme-driven-development.html

Nice command line usage - heroku:

• https://devcenter.heroku.com/articles/python

• https://devcenter.heroku.com/articles/quickstart

Layering of functionality - git:

• plumbing/porcelain paradigm

Deployment with git:

• http://joemaller.com/990/a-web-focused-git-workflow/