Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Finished up documentation.

  • Loading branch information...
commit bd75060798ebafcb775c264f8ae6c461e235a98a 1 parent cbcc14d
@kuyan authored
View
79 docs/building-extensions.rst
@@ -0,0 +1,79 @@
+===================
+Building Extensions
+===================
+
+Soil has facilities for adding extensions. Extensions are written in Python and can modify pretty much anything about the project, including the template's context. Extensions are Python classes (therefore, there could be multiple extensions in a single module or file, though, organizationally speaking, that's usually not too good of an idea).
+
+Requirements
+------------
+
+All soil extensions have three requirements in order to be run with a soil project:
+
+* Must have a valid name (See: :ref:`naming-extensions`)
+*
+* Must be registered with an entry point(s) (See: :ref:`entry-points`)
+
+.. _naming-extensions:
+
+Naming Extensions
+-----------------
+
+To be registered as an extension, the module containing the extension must be listed in the ``extensions`` list of the project's soilcfg.py and have a class name that:
+
+* Does not start with a ``_`` (underscore)
+* Ends with ``Extension``
+
+The extension does not have to have a specific subclass.
+
+.. _entry-points:
+
+Entry Points
+------------
+
+An extension can be called at two points during soil's runtime- pre-build/pre-run or post-build. Registering your extension with an entry point is simple::
+
+ entry_points = {'pre': self.does_something}
+ self.soil_application_instance.register_ext_entry_points(entry_points)
+
+There are only two entry points: ``pre`` (before a build or run takes place) and ``post`` (after a build takes place).
+
+.. important::
+ There is no post-run entry point. However, you can opt to have the server running the soil project reload if a certain file changes. Just add the file to the ``watched_files`` attribute of the ``soil.core.Soil`` instance.
+
+Your extension can be registered with one or both of the available entry points, but if it is not registered with any entry point, the extension will not be called.
+
+.. note::
+ Actually, regardless of whether you register your extension with an entry point or not, the ``__init__`` method *will* be called as soil traverses the ``extensions`` list in soilcfg.py and allows each extension to set up and register with an entry point. You *could* run something that way without registering an entry point, but please don't.
+
+ContextAdditions
+----------------
+
+I'm reluctant to add more documentation on extensions right now because I feel it could use a lot more work. In the meantime, check out the built-in `ContextAdditions extension <https://github.com/kuyan/soil/blob/master/soil/extensions/ContextAdditions.py>`_.
+
+.. Soil comes with one built-in extension: ``soil.extensions.ContextAdditions``. It allows names to be added from a root ``ctx_additions.py`` to the template context. Let's walk through it step-by-step.
+.. ::
+
+.. class ContextAdditionExtension(object):
+.. """Implements the ContextAddition extension."""
+.. def __init__(self, soil_instance):
+.. ...
+
+.. def inject(self):
+.. ...
+
+.. The ContextAdditions extension is small, spanning only 47 lines of code. Note that it has a valid extension name, ending in Extension and not starting with an underscore.
+.. Also note that the class takes one argument: all extensions are passed a pointer to the current ``soil.core.Soil`` instance, allowing them to add entry points, watched files, etc.
+.. ::
+
+.. def __init__(self, soil_instance):
+.. self.soil = soil_instance
+
+.. self.path = os.path.join(self.soil.projdir, 'ctx_additions.py')
+.. self.path = os.path.realpath(self.path)
+
+.. entry_points = {'pre': self.inject}
+.. self.soil.register_ext_entry_points(entry_points)
+.. self.soil.watched_files.append(self.path)
+
+.. Looking closer at the ``__init__`` method: with the current soil instance, you can access the project's configuration,
+
View
19 docs/extensions.rst
@@ -0,0 +1,19 @@
+.. _extensions:
+
+==========
+Extensions
+==========
+
+Adding Extensions
+=================
+
+To add extensions to a soil project, add the extension's module name (as a string) to the ``extensions`` list in soilcfg.py (see :ref:`soilcfg`)
+
+soil.extensions.ContextAdditions
+================================
+
+Soil comes with one extension by default: the ContextAdditions extension. The ContextAdditions extension allows you to add names to the context of all of your templates. To do this, add a ``ctx_additions.py`` to the root of your soil project. Any names/objects/attributes that are shown with ``dir()`` will be passed to the template's context.
+
+.. note::
+
+ If you find your ctx_additions.py growing a bit large or unruly, that's a sign that you probably need to use something else to build your project (like `Flask <http://flask.pocoo.org>`_).
View
30 docs/gettingstarted.rst
@@ -5,42 +5,31 @@ Soil aims to make the whole process of making a site easier.
Create a project
----------------
-Soil provides a 'skeleton' to make it easy to get started. So, to create
-a new project in the directory ``project/``, do::
+Soil provides a 'skeleton' to make it easy to get started. So, to create a new project in the directory ``project/``, do::
$ shovel new project/
-If you don't like the default application skeleton, there's nothing
-locking you in. All your project needs for soil to be able to use it
-is a ``soilcfg.py``.
+If you don't like the default application skeleton, there's nothing locking you in. All your project needs for soil to be able to use it is a ``soilcfg.py``.
soilcfg.py
----------
-``soilcfg.py`` acts as a marker that the directory it's stored in is a
-soil project and as configuration for soil. It's the only part of the
-project that can't be changed- the ``soilcfg.py`` has to be at the root
-of the project directory.
+``soilcfg.py`` acts as a marker that the directory it's stored in is a soil project and as configuration for soil. It's the only part of the project that can't be changed- the ``soilcfg.py`` has to be at the root of the project directory.
-Also, if you want to change the location of the the ``templates/``,
-``static/``, or ``build/`` directory/directories you need to denote that
-in ``soilcfg.py``. That's the only exception.
+.. note::
+ If you want to change the location of the the ``templates/``, ``static/``, or ``build/`` directory/directories you need to denote that in ``soilcfg.py``. That's the only exception.
Running your project
--------------------
-You can ``run`` your project to view it in your browser. To do this,
-(while you're still in your project directory), do::
+You can ``run`` your project to view it in your browser. To do this, (while you're still in your project directory), do::
$ shovel run
-And you should be able to open your browser, go to http://127.0.0.1:5000
-and see the soil landing page. That page is included as part of the
-default application skeleton and isn't required as part of a soil project.
+And you should be able to open your browser, go to http://127.0.0.1:5000 and see the soil landing page. That page is included as part of the default application skeleton and isn't required as part of a soil project.
Start editing templates
-----------------------
-Soil uses Jinja2 for templating. Jinja2 is really simple to use. One of
-the notable features is template inheritance.
+Soil uses Jinja2 for templating. Jinja2 is really simple to use. One of the notable features is template inheritance.
For example, say that your ``templates/_base.html`` looks like this:
@@ -87,8 +76,7 @@ To quote the Jinja2 documentation:
... the {% block %} [tag defines one block] that child templates can fill in. All the block tag does is to tell the template engine that a child template may override those portions of the template.
-Jinja2 has a lot more than can be explained on this page. If you want to learn
-more, you should check out `Jinja2's documentation`_
+Jinja2 has a lot more than can be explained on this page. If you want to learn more, you should check out `Jinja2's documentation`_.
Building your project
---------------------
View
4 docs/index.rst
@@ -16,7 +16,7 @@ General Usage
gettingstarted.rst
shovel.rst
soilcfg.rst
- soilcfg.py + extensions + should i be using soil or not?
+ extensions.rst
Development
-----------
@@ -25,7 +25,7 @@ Development
:maxdepth: 2
soil.rst
- building extensions
+ building-extensions.rst
Indices and tables
==================
View
10 docs/installing.rst
@@ -8,7 +8,7 @@ Installing with pip
Installing soil using ``pip`` is trivial::
- pip install soil
+ $ pip install soil
Installing with easy_install
----------------------------
@@ -16,15 +16,15 @@ Installing with easy_install
You `really`_ should be using pip (see :ref:`installing-with-pip`), but if
you want to use ``easy_install``, nobody's stopping you::
- easy_install soil
+ $ easy_install soil
Installing from source
----------------------
::
-git clone git:/github.com/kuyan/soil.git
-cd soil
-python setup.py install
+ $ git clone git:/github.com/kuyan/soil.git
+ $ cd soil
+ $ python setup.py install
.. _really: http://stackoverflow.com/questions/3220404/why-use-pip-over-easy-install
View
7 docs/modules.rst
@@ -1,7 +0,0 @@
-soil
-====
-
-.. toctree::
- :maxdepth: 4
-
- soil
View
19 docs/soil.extensions.rst
@@ -1,19 +0,0 @@
-extensions Package
-==================
-
-:mod:`extensions` Package
--------------------------
-
-.. automodule:: soil.extensions
- :members:
- :undoc-members:
- :show-inheritance:
-
-:mod:`ContextAdditions` Module
-------------------------------
-
-.. automodule:: soil.extensions.ContextAdditions
- :members:
- :undoc-members:
- :show-inheritance:
-
View
5 docs/soilcfg.rst
@@ -1,3 +1,5 @@
+.. _soilcfg:
+
soilcfg.py
==========
.. describe:: test
@@ -39,9 +41,10 @@ file for the project.
'build': 'build/'
}
+
.. describe:: extensions
- list of extensions to use. See TODO: add doc page on extensions
+ list of extensions to use. For more information, see the page on :ref:`extensions`.
::
extensions = ['package.of.soil.extension']
View
3  soil/extensions/ContextAdditions.py
@@ -17,9 +17,6 @@
import os
from soil.util import getattr_nested
-# 'post' is not run when serving
-# extensions need to end with Extension
-# there can be multiple extensions in a module
class ContextAdditionExtension(object):
Please sign in to comment.
Something went wrong with that request. Please try again.