The docs directory

This directory contains only files with an rst extension. You should organize these files into a flat hierarchy, meaning there should be no sub-directories under this.

Corresponds to [source] in the config file

Here is an example directory listing

total 64
drwxr-xr-x  7 robmadole  staff   238 Sep 21 22:05 .
drwxr-xr-x  8 robmadole  staff   272 Sep 21 22:05 ..
-rw-r--r--  1 robmadole  staff   322 Sep 14 22:23 installation.rst
-rw-r--r--  1 robmadole  staff  6628 Sep 21 22:05 reference.rst
-rw-r--r--  1 robmadole  staff  6437 Sep 11 16:36 sample_styles.rst
-rw-r--r--  1 robmadole  staff   211 Sep  8 12:16 tech_used.rst
-rw-r--r--  1 robmadole  staff  4178 Sep 21 12:01 welcome.rst

Each rST file should begin with a root title like this

=========================
Welcome Holy Grail Seeker
=========================

This title will become the identifier for this document.

The template directory

This directory should contain one index.html file that represents your one-page site. See the templating section for information on how this Jinja2 template should be formatted and what data is available when the site is generated.

Corresponds to [template] in the config file

The output directory

This directory contains your generated site. If your template has a index.html, your output directory will also. Any files in the template directory will be first copied to output before the site is generated.

Corresponds to [output] in the config file

Code block directive

To highlight source code, you can use the code block directive. This is copied from the Sphinx project and follows the same syntax.

To highlight Python code

.. code-block:: python
   from os.path import dirname

   # Where are we?
   here = dirname(__file__)

Produces this

from os.path import dirname

# Where are we?
here = dirname(__file__)

You can highlight other code as well, check the Pygments websites for a complete list.

Linking between documents

Handcrank uses a flat directory to store your rST documents. For example if you had the following directory listing in your docs directory.

• index.rst
• the_quest.rst
• the_grail.rst

You can link between the documents with the :doc: role.

I would like to learn more about :doc:`The grail <the_grail.rst`

This produces the following HTML

<a href="the_grail.rst" rel="doc-link">The grail</a>

You'll notice that unless you use Javascript to do something with this, the link is broken, the_grail.rst only exists in the source directory.

The default site created for you when you used handcrank startsite provides the Javascript that expands the appropriate tab when a link is clicked. See the source code for folders.js

Delegate methods

A delegate alters the behavior of the generator in some specific way.

sort_source_list(source_list)

Allows the order the documents appear in the page to be rearranged beyond the normal alphabetical. It's important to note that if you implement this method, you will have to call items_sort_alpha yourself as it will not happen automatically.

provide_extra_context()

Allows extra arguments via a dictionary to be added to the context when the Jinja2 template is rendered. The dictionary will extend the one created by the generator itself, so the only key you need to avoid is gathering.

A warning about using dict data types

It's probably been a while since reading an introduction to Python, but recall that dict data type keys are not ordered. Because of this, we have to take special care if utilizing them in these delegate methods. If you find yourself reaching for a dict, consider using an OrderedDict instead.

SourceList objects

If you examine a source_list object coming in from the generator you'll notice that the structure is a bit unexpected.

>>> source_list
<handcrank.generator.SourceList instance at 0x1023ed830>

Using a list comprehension, lets look at the first 25 characters of the source.

>>> [(i,j[:25],) for i,j in source_list]
[('installation.rst', 'Installation\n============'), ('reference.rst',
'API Reference\n==========='), ('sample_styles.rst', 'Sample
styling\n=========='), ('tech_used.rst', 'Projects and technology u'),
('welcome.rst', 'Getting started\n=========')]

Notice that iterating through the source list results in a tuple each time the loop moves to the next item. The tuple contains:

1. The document's basename, with extension
2. The source reStructuredText

('basename', 'source',)

Your delegate methods do not have to return a SourceList object, but they do need to adhere to the way the iterator works. Meaning each pass through the loop needs to provide the tuple.

Delegate helpers

To save some time, the following helper methods provide these features:

items_place_first(source_list, first_doc_name[, second_docs_name[, ...]])

Takes a source list and places the doc names passed in

items_sort_alpha(source_list)

Sorts the source files by title, alphabetically

You can see both of these helper methods used in this example:

def sort_source_list(self, source_list):
    """
    Put installation.rst and welcome.rst first in the list
    """
    return self.items_place_first(
        self.items_sort_alpha(source_list),
        'installation.rst', 'welcome.rst')

Adding extra context

The example above used provide_extra_context to allow a formatted date to be added to the available data when the template renders.

Taking another look at that:

def provide_extra_context(self):
    """
    Adds a generation time that can be used in the template like:

        {{ time_generated }}

    """
    return {'time_generated': datetime.now().strftime('%b %d, %Y')}

A dictionary is returned containing one key, time_generated.

To use this within the template is fairly straight-forward.

<!DOCTYPE html>
<html lang="en">
    <head>
    <meta charset="utf-8" />
    <title>Handcrank Site Generator</title>
    </head>
    <body>
        <header>Documentation</header>

        {% for title in gathering %}
            <article class="folder">
                <h1>{{ title }}</h1>
                {{ gathering[title]['fragment'] }}
            </article>
        {% endfor %}

        <footer>Generated on {{ time_generated }}</footer>
    </body>
</html>

First sub-heading

Bullet lists

• This is item 1
• This is item 2
• Bullets are "-", "*" or "+". Continuing text must be aligned after the bullet and whitespace.

Enumerated lists

3. This is the first item
4. This is the second item
5. Enumerators are arabic numbers, single letters, or roman numerals
6. List items should be sequentially numbered, but need not start at 1 (although not all formatters will honour the first index).
7. This item is auto-enumerated

Definition lists

what

Definition lists associate a term with a definition.

how

The term is a one-line phrase, and the definition is one or more paragraphs or body elements, indented relative to the term. Blank lines are not allowed between term and definition.

Field lists

Option lists

Literal blocks

A paragraph containing only two colons indicates that the following indented or quoted text is a literal block.

Whitespace, newlines, blank lines, and
all kinds of markup (like *this* or
\this) is preserved by literal blocks.

The paragraph containing only '::'
will be omitted from the result.

The :: may be tacked onto the very end of any paragraph. The :: will be omitted if it is preceded by whitespace. The :: will be converted to a single colon if preceded by text, like this:

It's very convenient to use this form.

Literal blocks end when text returns to the preceding paragraph's indentation. This means that something like this is possible:

    We start here
  and continue here
and end here.

Per-line quoting can also be used on unindented literal blocks:

> Useful for quotes from email and
> for Haskell literate programming.

Code blocks

class HtmlCodeBlock(Directive):
    """
    Borrowed from the Sphinx project
    """

    has_content = True
    required_arguments = 1
    optional_arguments = 0
    final_argument_whitespace = False
    option_spec = {
        'linenos': directives.flag,
    }

    def run(self):
        code = u'\n'.join(self.content)

        linenos = 'linenos' in self.options
        lexer = get_lexer_by_name(self.arguments[0])
        formatter = HtmlFormatter(linenos=linenos)

        hi_code = highlight(code, lexer, formatter)

        raw = nodes.raw('', hi_code, **{'format': 'html', 'source': None})
        return [raw]

directives.register_directive('code-block', HtmlCodeBlock)

Line blocks

Block quotes

Block quotes are just:

Indented paragraphs,

and they may nest.

Grid table

Transition

A transition marker is a horizontal line of 4 or more repeated punctuation characters.

A transition should not begin or end a section or document, nor should two transitions be immediately adjacent.

Footnotes

Footnote references, like [5]. Note that footnotes may get rearranged, e.g., to the bottom of the "page".

Autonumbered footnotes are possible, like using [1] and [2].

They may be assigned 'autonumber labels' - for instance, [4] and [3].

Citations

Citation references, like [CIT2002]. Note that citations may get rearranged, e.g., to the bottom of the "page".

Citation labels contain alphanumerics, underlines, hyphens and fullstops. Case is not significant.

Given a citation like [this], one can also refer to it like this.

Hyperlinks

Images