Loslassa 0.3.10
Just another toy static website generator
License: BSD

|TravisBadge|_  |CoverallBadge|_  |PyPiBadge|_ |CommitMood|_

.. |TravisBadge| image:: https://travis-ci.org/obestwalter/loslassa.png?branch=master
.. _TravisBadge: https://travis-ci.org/obestwalter/loslassa

.. |CoverallBadge| image:: https://coveralls.io/repos/obestwalter/loslassa/badge.png?branch=master
.. _CoverallBadge: https://coveralls.io/r/obestwalter/loslassa?branch=master

.. |PyPiBadge| image:: https://badge.fury.io/py/loslassa.svg
.. _PyPiBadge: http://badge.fury.io/py/loslassa

.. |PyPiBadgeOwn| image:: http://b.repl.ca/v1/get_it-on_pypi%21-green.png
.. _PyPiBadgeOwn: https://pypi.python.org/pypi/Loslassa

.. |CommitMood| image:: http://b.repl.ca/v1/Olivers_Commit_Mood-ExitedAboutBadges%21-green.png
.. _CommitMood: http://www.youtube.com/watch?v=5NzPd-xW4YY


`Huboard issues <https://huboard.com/obestwalter/loslassa>`_

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 <http://docutils.sourceforge.net/rst.html>`_:

        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 <http://sphinx-doc.org>`_ documentation generator.

Sphinx Porcelain
''''''''''''''''
My favorite way to create documentation for `Python <http://python.org>`_ 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 <http://git-scm.com/book/ch9-1.html>`_ 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 <http://git-scm.com>`_ is a fantastic `DVCS-System <https://en.wikipedia.org/wiki/Distributed_revision_control>`_ 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 <https://en.wikipedia.org/wiki/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  <http://www.pocoo.org/projects/werkzeug/#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 <http://www.pocoo.org/projects/flask/#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 <http://plumbum.readthedocs.org/en/latest/>`_ 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 <http://en.wikipedia.org/wiki/Swabian_German>`_ 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 ;).