Loslassa 0.3.9-testing2

Just another toy static website generator

Huboard issues

Loslassa

Static website generator using established OSS tools to do the job.

Mainly a lab for me play with fancy libraries and OSS workflows

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

TODO but first find out which git library to use

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.

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 …

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 ;).