<commit_before>.. _static-rendering:

======================================
Deploy PyBlosxom with Static Rendering
======================================

Summary
=======

Static rendering made its first appearance in PyBlosxom 1.0.  It fills
the functionality gap for people who want to use PyBlosxom, but don't
have a web-server with CGI installed, don't have CGI access, or can't
run PyBlosxom for one of a myriad of other reasons.  Static rendering
allows these people to run PyBlosxom on their local machine, write
blog entries, render their entire site into HTML, and then use ftp or
some other file copy method to move the pages up to their static
website.

PyBlosxom's static rendering allows for incremental building.  It can
scan your entries, figure out what's changed, and render only the
pages that need re-rendering.

Beyond that, it's not particularly sophisticated.


Configuring static rendering
============================

These are the instructions for configuring static rendering in PyBlosxom.

1. **Uncomment ``static_dir`` in your ``config.py`` file.**

   This is the directory we will save all the static output.  The value of 
   ``static_dir`` should be a string representing the **absolute path** of the 
   output directory for static rendering.

2. **Uncomment ``static_flavours`` in your ``config.py`` file.**

   The value of ``static_flavours`` should be a list of strings representing 
   all the flavours that should be rendered.  This defaults to 
   ``[ "html" ]``.

3. **Uncomment ``static_monthnames`` in your ``config.py`` file.**

   The value (either ``1`` or ``0``) will determine if you want month 
   names (such as ``April``) in the static pages.

4. **Uncomment ``static_monthnumbers`` in your ``config.py`` file.**

   The value (either ``1`` or ``0``) will determine if you want month 
   numbers (such as ``04`` for ``April``) in the static pages.

5. **Set ``base_url`` in your ``config.py`` file to the base url your 
   blog will have.**

   For example, if your ``static_dir`` were set to ``/home/joe/public_html`` 
   and the url for that directory were ``http://www.joe.com/~joe/``, then 
   you probably want to set your base_url like this::

      py["base_url"] = "http://www.joe.com/~joe/"


Here's an example of static rendering configuration::

   py["static_dir"] = "/home/joe/public_html/static/"
   py["static_flavours"] = ["html"]
   py["static_monthnames"] = 0     # i do not want month names
   py["static_monthnumbers"] = 1   # i do want month numbers



Running static rendering
========================

There are two ways to run static rendering.  The first is to render
your entire blog from scratch (see "render everything") and the second
is to render only the parts of the blog that will be different because
of new blog entries or updated blog entries (see "incremental rendering").


Render everything
-----------------

To render all pages in your blog, ``cd`` into the directory that
contains your ``config.py`` file and run::

   % pyblosxom-cmd staticrender

Or from any directory run::

   % pyblosxom-cmd staticrender --config </path/to/blog_dir>

where ``</path/to/blog_dir>`` is replaced by the path of the directory
that contains your ``config.py`` file.  For example::

   % pyblosxom-cmd staticrender --config /home/joe/blog/

Lots of output will appear as PyBlosxom figures out all the urls that need 
to be rendered and then renders them.


Incremental rendering
---------------------

To find all the entries that have changed since you last rendered
them and then re-render just those entries, do::

   % pyblosxom-cmd staticrender --config </path/to/blog_dir> --incremental
<commit_msg>Addition to static rendering docs.<commit_after>.. _static-rendering:

======================================
Deploy PyBlosxom with Static Rendering
======================================

Summary
=======

Static rendering made its first appearance in PyBlosxom 1.0.  It fills
the functionality gap for people who want to use PyBlosxom, but don't
have a web-server with CGI installed, don't have CGI access, or can't
run PyBlosxom for one of a myriad of other reasons.  Static rendering
allows these people to run PyBlosxom on their local machine, write
blog entries, render their entire site into HTML, and then use ftp or
some other file copy method to move the pages up to their static
website.

PyBlosxom's static rendering allows for incremental building.  It can
scan your entries, figure out what's changed, and render only the
pages that need re-rendering.

Beyond that, it's not particularly sophisticated.


Configuring static rendering
============================

These are the instructions for configuring static rendering in PyBlosxom.

1. **Uncomment ``static_dir`` in your ``config.py`` file.**

   This is the directory we will save all the static output.  The value of 
   ``static_dir`` should be a string representing the **absolute path** of the 
   output directory for static rendering.

2. **Uncomment ``static_flavours`` in your ``config.py`` file.**

   The value of ``static_flavours`` should be a list of strings representing 
   all the flavours that should be rendered.  This defaults to 
   ``[ "html" ]``.

3. **Uncomment ``static_monthnames`` in your ``config.py`` file.**

   The value (either ``1`` or ``0``) will determine if you want month 
   names (such as ``April``) in the static pages.

4. **Uncomment ``static_monthnumbers`` in your ``config.py`` file.**

   The value (either ``1`` or ``0``) will determine if you want month 
   numbers (such as ``04`` for ``April``) in the static pages.

5. **Set ``base_url`` in your ``config.py`` file to the base url your 
   blog will have.**

   For example, if your ``static_dir`` were set to ``/home/joe/public_html`` 
   and the url for that directory were ``http://www.joe.com/~joe/``, then 
   you probably want to set your base_url like this::

      py["base_url"] = "http://www.joe.com/~joe/"


Here's an example of static rendering configuration::

   py["static_dir"] = "/home/joe/public_html/static/"
   py["static_flavours"] = ["html"]
   py["static_monthnames"] = 0     # i do not want month names
   py["static_monthnumbers"] = 1   # i do want month numbers



Running static rendering
========================

There are two ways to run static rendering.  The first is to render
your entire blog from scratch (see "render everything") and the second
is to render only the parts of the blog that will be different because
of new blog entries or updated blog entries (see "incremental rendering").


Render everything
-----------------

To render all pages in your blog, ``cd`` into the directory that
contains your ``config.py`` file and run::

   % pyblosxom-cmd staticrender

Or from any directory run::

   % pyblosxom-cmd staticrender --config </path/to/blog_dir>

where ``</path/to/blog_dir>`` is replaced by the path of the directory
that contains your ``config.py`` file.  For example::

   % pyblosxom-cmd staticrender --config /home/joe/blog/

Or, if the location of your ``config.py`` file is on your
``$PYTHONPATH`` then you can run ``pyblosxom-cmd staticrender`` from
any directory without giving the ``--config`` option.

Lots of output will appear as PyBlosxom figures out all the urls that need 
to be rendered and then renders them.


Incremental rendering
---------------------

To find all the entries that have changed since you last rendered
them and then re-render just those entries, do::

   % pyblosxom-cmd staticrender --config </path/to/blog_dir> --incremental

{'fraction_non_alphanumeric': 0.13423173470735897, 'fraction_numerical': 0.003963535473642489, 'mean_word_length': 3.8712998712998714, 'pattern_counts': {'":': 0, '<': 9, '<?xml version=': 0, '>': 9, 'https://': 0, 'lorem ipsum': 0, 'www.': 4, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '4098957', 'n_tokens_mistral': 2197, 'n_tokens_neox': 2060, 'n_words': 990}