.. Blogdegins documentation master file, created by
sphinx-quickstart on Mon Jul 23 14:14:24 2012.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to Blogdegins's documentation!
======================================
Generate static html code with python code files and their
associated Mako templates, css and javascript files,
with a command line utility.
Work with the skeleton you wont.
It includes a skeleton base on:
* `html5boilerplate `_.
* `jquery `_.
* `Mako `_.
* `Webassets `_.
* `Sass `_.
* `Compass `_.
The directories tree is well organized, encouraging to work
with multiple files in development (css, mako, javascript and python).
Separate external lib files and yours own files.
Write the css code in scss language. Use the compass mixins. If you wont.
In no debug mode, css and javacript files are concatenaded and minified
in only one file.
Generate tags by version, and can synchronize with a server.
Available commands:
* init :ref:`init`
* skeleton :ref:`skeleton`
* render :ref:`render`
* page :ref:`page`
* widget :ref:`widget`
* rsync :ref:`rsync`
Quick Start
===========
.. _init:
Build a project
---------------
Create a new project directory with the command::
blogdegins init myblog
This command creates the `myblog` directory with the next structure::
myblog
├── assets
│ ├── h5bp+jquery
│ └── sample-logo
├── blogdegins.ini
├── htmlrendercode
│ ├── assets.py
│ ├── content.js
│ ├── content.mako
│ ├── content.py
│ ├── content.scss
│ ├── __init__.py
│ ├── mymako.py
│ ├── base.js
│ ├── base.mako
│ ├── base.py
│ ├── base.scss
│ ├── README.rst
│ ├── scss-mixins
│ │ └── _ginsgrid.scss
│ ├── templates
│ │ └── logo.mako
│ └── widgets
│ ├── boxlist
│ │ ├── boxlist.js
│ │ ├── boxlist.mako
│ │ ├── boxlist.py
│ │ ├── boxlist.scss
│ │ ├── __init__.py
│ │ └── newtab2.css
│ ├── __init__.py
├── Makefile
├── tags
└── watch.sh
* The `blogdegins.ini` file is the configuration file.
* The `assets` directory contains the assets skeletons.
It's the structure of the preconfigured directories
with js, css, img files, etc.
* The `htmlrendercode` contains the python code that generate the html code.
* The `tags` directory contains the final result, organized by `tag` versions.
Intiatially it contains a copy of assets directory,
and the output of the generated static html::
tags
└── 0.00.aa
├── 404.html
├── apple-touch-icon-114x114-precomposed.png
├── apple-touch-icon-144x144-precomposed.png
├── apple-touch-icon-57x57-precomposed.png
├── apple-touch-icon-72x72-precomposed.png
├── apple-touch-icon.png
├── apple-touch-icon-precomposed.png
├── crossdomain.xml
├── favicon.ico
├── humans.txt
├── index.html
├── robots.txt
├── sample-64x64.png
├── sample.png
└── static
├── css
│ ├── app
│ │ ├── content.scss -> ../../../../../htmlrendercode/content.scss
│ │ ├── content.scss.css
│ │ ├── base.scss -> ../../../../../htmlrendercode/base.scss
│ │ └── base.scss.css
│ ├── libs
│ │ └── normalize
│ │ ├── normalize-2.0.0.css
│ │ └── normalize.css -> ./normalize-2.0.0.css
│ ├── packed.css
│ └── widgets
│ ├── boxlist.scss -> ../../../../../htmlrendercode/widgets/boxlist/boxlist.scss
│ └── boxlist.scss.css
├── font
│ ├── AlexBrush-Regular.ttf
│ └── OFL.txt
├── img
└── js
├── bottom
│ ├── app
│ │ ├── content.js -> ../../../../../../htmlrendercode/content.js
│ │ └── base.js -> ../../../../../../htmlrendercode/base.js
│ ├── libs
│ │ ├── jquery
│ │ │ ├── jquery-1.7.2.js
│ │ │ └── jquery.js -> jquery-1.7.2.js
│ │ └── plugins.js
│ └── widgets
│ └── boxlist.js -> ../../../../../../htmlrendercode/widgets/boxlist/boxlist.js
├── bottom.js
├── top
│ ├── modernizr-2.5.3.min.js
│ └── modernizr.js -> ./modernizr-2.5.3.min.js
└── top.js
.. _skeleton:
Create a new tag
----------------
Create a new tag output directory with the command::
blogdegins skeleton
Execute this command in the `myblog` directory to create a new skeleton,
a new directory in the `tags` directory with the name of the current tag.
The current tag is defined in the blogdegins.ini file.
The selected skeleton is the one configurated in the blogdegins.ini file.
.. _render:
Create your static html code
----------------------------
Create your index.html with the command::
blogdegins render
This command executes the code of the `htmlrendercode` directory,
generating the content of `index.html` file.
The index.html file is created in the current tag directory.
The called code is::
from base import get_base
base = get_base(code_path, output_path, debug)
html = base.render()
`get_base` is the only function being called from blogdegins.
The rest is up to you.
This function must return a class with a `render` method.
The `render` method must return a string with the html code.
The parameters are::
:param code_path: path where python and templates code reside.
:param output_path: current output tag directory.
:param debug: True if you want debug.
.. _page:
Create a new page
-----------------
This command create a new `page template`::
blogdegins page name
It will create four files: *name.py*, *name.js*, *name.css* and *name.mako*.
Though the javascript and mako code could be inside the `name.py` file,
or css could be inside of mako file,
I prefer to maintain each code type in their own file,
in order to benefit of editors syntax tools.
Addition to creating the files,
two symbolic links are created:
* A link to javascript file is created in the current output tag directory
plus **static/js/bottom/app**.
* A link to css file is created in the current output tag directory
plus **static/css/app**.
If some file already exists, it is not overridden.
.. _widget:
Create a new widget
-------------------
This command create a new `widget`::
blogdegins widget name
It will create four files: *name.py*, *name.js*, *name.css* and *name.mako*
in the widgets directory.
Addition to creating the files,
two symbolic links are created:
* A link to javascript file is created in the current output tag directory
plus **static/js/bottom/widgets**.
* A link to css file is created in the current output tag directory
plus **static/css/widgets**.
If some file already exists, it is not overridden.
.. _rsync:
Publish the static html code
----------------------------
You can publish your static html code in the configurated servers
with the command::
blogdegins rsync
Assets
======
Assets currently avaiable:
h5bp+jquery
-----------
A skeleton based on:
* `html5boilerplate `_.
* `jquery `_.
* `Mako `_.
* `Webassets `_.
* `Sass `_.
* `Compass `_.
.. warning:: needed webassets >= 0.8.dev.
You need to download this webassets version
from ``_
sample-logo
-----------
It's not a skeleton.
A utility for build all icons needed in h5bp
if you have a logo in svg format.
Html render code
================
Blogdegins execute the next code when `render` command is executed::
from base import get_base
base = get_base(code_path, output_path, debug)
html = base.render()
where:
* code_path: path where python and templates code reside.
* output_path: current output tag directory.
* debug: True if you want debug.
That is, in your `htmlrendercode` directory you only need a ``base.py`` module,
with a ``get_base()`` factory function that returns a class with the
``render`` method.
In the supplied code, I use the next packages to generate html code:
* ``ghtml`` (``Mako`` and ``ginsfsm``)
* ``webassets``
blogdegins.ini
==============
This is the initial configuration file::
[DEFAULT]
current_tag = 0.00.aa
[tags]
0.00.aa =
[0.00.aa]
assets = assets/h5bp+jquery
remote-server =
In each tag you configure the assets used to create a new tag skeleton
and the remote server to rsync the output.
The current tag it will be used with the ``render`` and ``rsync`` commands.
License
-------
Copyright (c) 2012, Ginés Martínez Sánchez.
`blogdegins` is released under terms of the
`MIT License `_.
Indices and tables
==================
* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`