PyBlue
Project description
PyBlue provides a simple way to generate static files used to present data analysis reports, personal webpages, static blogs etc.
Features
zero configuration, PyBlue just needs to be pointed to a directory and it works
requires no initialization or settings file, nor does it require a certain directory layout
minimalistic design with a tiny codebase of around 400 lines of Python
add one line to each HTML file turn on the functionality of the extension modules
simple cross-linking to all content within the site
supports table of contents and image galleries
optional tagging or grouping of files with regular expression patterns
uses the python Mako templates which means that there are no limitations to what you can do within a template ;-)
PyBlue is a modification of the PyGreen project that is being expanded to include more data oriented functionality.
Demo Sites
Main demo site:
The PyBlue Demo site at http://www.pyblue.org
Other sites:
Installation
Requirements: setuptools and/or pip needs to be installed.
To install use one the common installation methods (you may need to use sudo to install)
easy_install pyblue
or
pip install pyblue
This will install the pyblue script.
If you already have pyblue installed you can upgrade via easy_install -U pyblue or pip install --upgrade pyblue
Quick Start
Point pyblue to a directory and serve the files from it:
pyblue serve -f ~/tmp/mywebsite
add an index.html page into that directory. Visit http://localhost:8080 to see the site
What does the tool do?
PyBlue generates static sites. Typically this involves two steps.
Serving the file during the site development. PyBlue will serve the files from a directory and presents the latest version of the file. This allows the site creator to write the site and check continuously what the output will look like. The site can be written in Markdown and the Mako templating engine.
Once the site is ready to be published the site generation command can be used to create a static copy of the site in the desired folder. The files in the output folder can be distributed and can be opened in a browser if stored on the local filesystem or they can be served via a static web-server such as apache, nginx etc.
Demonstration Server
To generate the content of the included demo server (shown at http://www.pyblue.org):
git clone git@github.com:ialbert/pyblue.git
then launch pyblue with
pyblue serve -f pyblue/sites/demo
Then visit http://localhost:8080 to see the site. Look in the sites/demo folder to see the sources that create the site.
To generate a static version of the site into the ~/tmp/www/ folder type:
pyblue gen -f sites/demo ~/tmp/www
Templates
Files with the .html extension will be processed via Mako templates. For example if the folder contains a file index.html with the following code:
<p>Hello, my age is ${30 - 2}.</p>
When going to http://localhost:8080, you will see:
<p>Hello, my age is 28.</p>
Visit the [Mako templates][mako] site to see the full power of the templating system.
Context
PyBlue allows embedding metadata into the files as Mako comments. For example adding the text below into an html file sets the name, a sort order (used to order listings) and the tags (used to group files) of the page:
##name Home Page ##sortkey 1 ##tags home intro ##foo bar
Any meta tag added to the page may be later retrieved in the page via the default variable f (current file) context variable: ${f.foo}.
This makes it really easy to add navigation bars and breadcrumbs with location specific rendering. See the demo site for examples.
Extensions
PyBlue offers functions that can be used to generate tables of contents or galleries. See the demo site for examples. for details:
# generate a table of contents ${toc()} # generate a table of contents for # the pages tagged as 'data' ${toc(tag='data')}
The sites/demo folder contain numerous examples on the usage.
Generating Site
PyBlue can export all the files of the input folder after having the .html files processed by Mako. To do so perform the following:
pyblue gen -f input_folder output_folder
Then look at the output_folder.
Hidden files or those with the .mako or .py, extension will not be visited by pyblue gen. This is useful to avoid generating macros files or templates to inherit.
Note that the gen command will also create all sub-folders. Only files under a certain size will be copied automatically (this is to avoid copying potentially large files back and forth). To copy large files set up a separate synchronization script. Note that the relative links will still work.
Templates
There are default templates included in the templates folder. These will be automatically included in the template search path. To override them create identically named templates in your site’s root folder.
View the default templates in the source code.
Example Sites
There are a number of [example sites][sites] included in the sites folder.
You may serve/generate each site independently to see what they contain. These sites demonstrate the utility functions that are included with PyBlue and the default templates. For example: generating tables of content, matching and displaying links with certain properties.
Advanced Functionality
PyBlue may be minimalistic but it is not simplistic. It supports an easy embedding of any template context into the template.
Adding a settings.py python module into the root of the site will make that module accessible within the template context under the variable p.settings. What this means is that you can run any type of python based code and then expose it later within the template context.
For example suppose that one wants to query sample information from a database. Place the python query to the database in the settings.py module and then return that in the template. For example a settings.py module could contain:
def query(): results = "<some python code goes here>" return results
Then every single template that is created could access the results of that code via:
p.settings.query()
Inserting the content of another file can be performed with source("demo.py") Note that the source command can also take parameters such as start and end. When those are set only the region that is between the matching regular expressions will be included.
Capturing the output of running a program would be achieved via execute("python demo.py")
Licensing
PyBlue is being developed by Istvan Albert see https://github.com/ialbert
PyBlue is built on PyGreen created by Nicolas Vanhoren see https://github.com/nicolas-van)
PyBlue uses the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for pyblue-1.0.9.macosx-10.8-intel.exe
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4669a4147a3099871edb468a95567e0b8ef61597f73fdfa83600798363cfad11 |
|
MD5 | af156893aa6ba97897c7596018190436 |
|
BLAKE2b-256 | ab6fa91acfbf6e556d267472b773178c49e2e18c6a6960063c906a7bca9a422a |