More docs. [skip ci]

docs/conf.py

@@ -41,6 +41,7 @@
     'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.extlinks',
+    'sphinx.ext.todo',
     'repoze.sphinx.autointerface',
 ]
 
@@ -86,8 +87,8 @@
 pygments_style = 'sphinx'
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
-todo_include_todos = False
-
+todo_include_todos = True
+todo_link_only = True
 
 # -- Options for HTML output ----------------------------------------------
 

docs/first_theme.rst

@@ -1,24 +1,13 @@
-==============================
- Getting Started With A Theme
-==============================
+==================
+ Creating a Theme
+==================
 
 .. highlight:: html
 
 Creating a theme proceeds as `documented in the Nikola reference
 <https://getnikola.com/theming.html#>`_. This document will focus on
-the template features that nti.nikola_chameleon provides.
-
-.. note:: As you'll see in the examples below, the `template variables
-          Nikola defines
-          <https://getnikola.com/template-variables.html>`_ are made
-          available in the ``options`` dictionary, one of `the
-          standard names
-          <https://docs.zope.org/zope2/zope2book/AppendixC.html#built-in-names>`_
-          available to page templates. The ``context`` standard name
-          is often a Nikola post object (depending on the specific template).
-
-.. The above should probably be elsewhere, in a different type of
-   "getting started" document. That doc should talk about traversal.
+the template features that nti.nikola_chameleon provides. Make sure
+you've read :doc:`getting_started` before reading this.
 
 Your theme should be laid out according to the Nikola documentation..
 The only directory that nti.nikola_chameleon is interested in is your
@@ -80,7 +69,7 @@ expression type is available, the traversal based mechanism is much
 more flexible because it allows themes that extend yours to provide a
 new ``base.tmpl`` view. It is also useful to provide different macros
 depending on the ``context`` object (or whatever objects you traverse
-through). For more on that, see :doc:`narr` and :ref:`zcml`.
+through). For more on that, see :doc:`using_zca` and :ref:`zcml`.
 
 Macros
 ======
@@ -148,7 +137,7 @@ type::
 However, as with templates, the use of the ``macro:`` expression type
 allows themes to extend us and replace that macro with their own
 version, and it allows us to produce macros that do different things
-depending on context. For more on that, see :doc:`narr` and :ref:`zcml`.
+depending on context. For more on that, see :doc:`using_zca` and :ref:`zcml`.
 
 
 .. caution:: If you implement a macro of the same name in two

docs/getting_started.rst

@@ -0,0 +1,94 @@
+=================
+ Getting Started
+=================
+
+.. note:: For the purposes of this document, the implementation of
+          `Zope Page Templates
+          <https://docs.zope.org/zope2/zope2book/AppendixC.html#define-define-variables>`_
+          provided by `Chameleon
+          <https://chameleon.readthedocs.io/>`_
+          working together with `z3c.pt
+          <https://pypi.python.org/pypi/z3c.pt>`_ will simply be
+          referred to as "page templates" or abbreviated to "ZPT."
+
+Introduction
+============
+
+This package allows developing Nikola templates using Chameleon.
+Chameleon is a fast implementation of the Zope Page Templates
+specification. Unlike template systems such as Jinja2 or Mako, page
+templates are designed to be valid (X)HTML and may be edited in HTML
+editors. It's even possible to use visual design tools to produce
+pages that are then relatively easily turned into page templates;
+sometimes it's even possible to edit those templates again in the same
+visual design tool.
+
+Component Architecture
+======================
+
+Page templates can be much more than that, though. When combined with
+the Zope `component architecture
+<https://zopecomponent.readthedocs.io/>`_ (ZCA), they can be designed
+to be extensible and flexible in a way that the simple template
+inheritance schemes of other template systems cannot match. This
+package is designed to embrace that, making it possible to create and
+extend templates and themes very easily.
+
+.. note::
+
+  Although we believe the component architecture can be used to make
+  themes flexible and make changing and customizing them through
+  inheritance or configuration easier, *you are not required to use
+  these features* if you don't want to. You can build an entire theme
+  just based on the files in the templates directory and the Chameleon
+  ``load:`` expression.
+
+For a discussion of how the ZCA can be leveraged in your themes, see :doc:`using_zca`.
+
+Prerequisites
+=============
+
+To create templates with this package, you'll need a basic
+understanding of the following:
+
+- the page templates `language <https://chameleon.readthedocs.io/en/latest/reference.html>`_
+- `path expressions
+  <https://docs.zope.org/zope2/zope2book/AppendixC.html#tales-path-expressions>`_
+
+
+It may be helpful to understand object traversal, similar to what can
+be used in `the Pyramid web framework
+<https://docs.pylonsproject.org/projects/pyramid/en/latest/narr/traversal.html>`_.
+We use `zope.traversing
+<https://pypi.python.org/pypi/zope.traversing>`_ to implement
+traversal, and provide several "path adapters" to make traversal in
+path expressions more convenient.
+
+.. todo:: Write about the standard path adapters (meta,
+          formatted_date) and views (@@macros, @@post_text) we
+          provide, with examples.
+
+Macros and Viewlets
+-------------------
+
+Most templates will also make use of `macros
+<https://chameleon.readthedocs.io/en/latest/reference.html#macros-metal>`_,
+and many will also use `viewlets
+<https://pypi.python.org/pypi/zope.viewlet>`_. We'll discuss how each
+of these can be used to develop flexible templates in :doc:`macros`
+and :doc:`viewlets`, respectively. Complete examples using these
+techniques can be found in `base-chameleon
+<https://github.com/NextThought/nti.nikola_themes.base-chameleon>`_,
+and its extension using bootstrap3, `bootstrap3-chameleon
+<https://github.com/NextThought/nti.nikola_themes.bootstrap3-chameleon>`_.
+
+Template Variables
+==================
+
+Your templates will have access to all of the `template variables
+Nikola defines <https://getnikola.com/template-variables.html>`_.
+These are made available in the ``options`` dictionary, one of `the
+standard names
+<https://docs.zope.org/zope2/zope2book/AppendixC.html#built-in-names>`_
+available to page templates. The ``context`` standard name is often a
+Nikola post object (depending on the specific template).

docs/index.rst

@@ -1,14 +1,21 @@
 .. include:: ../README.rst
 
 Once you have successfully installed the project, proceed to
-:doc:`first_theme`. For a more complete understanding of how this
-package works, see :doc:`narr`.
+:doc:`getting_started`. For a more complete understanding of how this
+package works, see :doc:`using_zca`.
+
+.. caution:: This documentation is a work in progress.
+
 
 .. toctree::
    :maxdepth: 2
 
+   getting_started
    first_theme
-   narr
+   using_zca
+   macros
+   viewlets
+   inheritance
    api
    changelog
 

docs/inheritance.rst

@@ -0,0 +1,7 @@
+===================
+ Theme Inheritance
+===================
+
+.. todo:: Write inheritance.
+
+Talk about how and why. Overloading bits and pieces. ZCA makes it easy.

docs/macros.rst

@@ -0,0 +1,10 @@
+==============
+ Using Macros
+==============
+
+.. todo:: Write macro section.
+
+- Using macros from the same template: template/macros/macro_name
+- Using defined templates: macro:macro_name
+  - Automatically discovered in .macro.pt files for any triple.
+  - Registered from ZCML for specific triples.

docs/using_zca.rst

@@ -0,0 +1,20 @@
+=======================================
+ Leveraging the Component Architecture
+=======================================
+
+.. todo:: Write ZCA section
+
+Theory of Operation
+===================
+
+Talk about component lookup: context, request/layer, view and how we
+can register macros and viewlets for each of those things.
+
+Talk about what each represents (object in use, details about what
+we're asking for, how we're handling the asking).
+
+Talk about layers applied to the "request".
+
+Talk about the different page kinds.
+
+Talk about comment systems.

docs/viewlets.rst

@@ -0,0 +1,10 @@
+================
+ Using Viewlets
+================
+
+.. todo:: Write viewlet section.
+
+- The provider:viewlet_manager expression
+- Registered in ZCML
+- Standard viewlet manager types.
+- New viewlet managers in ZCML