render_engine package

Submodules

render_engine.blog module

class render_engine.blog.Blog

Bases: render_engine.collection.Collection

Custom Collection Class with Archiving Enabled and the RSS Feed

Todos:
  • Add Support for JSON Feeds
  • Rename the archive items so they are not private
archive_reverse = True
archive_sort = 'date_published'
content_type

alias of BlogPost

feeds

Built-in mutable sequence.

If no argument is given, the constructor creates a new empty list. The argument must be an iterable if specified.

has_archive = True
class render_engine.blog.BlogPost(**kwargs)

Bases: render_engine.page.Page

Page Like object with slight modifications to work with BlogPosts.

list_attrs = ['tags']
rss_feed_item
template = 'blog_post.html'

render_engine.collection module

class render_engine.collection.Collection

Bases: object

Collection objects serve as a way to quickly process pages that have a LARGE portion of content that is similar or file driven.

The most common form of collection would be a Blog, but can also be static pages that have their content stored in a dedicated file.

Currently, collections must come from a content_path and all be the same content type.

Example:

from render_engine import Collection

@site.register_collection()
class BasicCollection(Collection):
    pass
archive

Create a Page object for the pages in the collection

archive_reverse = False
archive_sort = 'title'
archive_template = 'archive.html'
content_items = []
content_path = ''
content_type

alias of render_engine.page.Page

engine = None
feeds = []
get_subcollections()
has_archive = False
includes = ['*.md', '*.html']
items_per_page = 10
markdown_extras = ['fenced-code-blocks', 'footnotes']
pages
paginated = False
routes = ['']
slug
subcollections = []
template = 'page.html'
title = ''

render_engine.engine module

class render_engine.engine.Engine

Bases: object

This is the jinja2 engine that is builds your static site. Use Engine.run() to output the files to the designated output path.

environment

The jinja2 environment class that controls which templates should be called and applied.

extension = '.html'

the extension to use in the rendered files

get_template(template: str)

fetches the requested template from the environment. Purely a convenience method

render(page: Type[render_engine.page.Page], template: Optional[str] = None, **kwargs)

generate rendered HTML from from the called template

This is what builds the pages into HTML.

If a template attribute is defined or passed in then load the template and return the output. Otherwise return the content as HTML.

Parameters:
  • page – the page object to render into html
  • template – the name of a template to render
  • kwargs – values that would be passed into the called template. If no template value
template_path = 'templates'

the directory to find templates for render_engine.page.Page()-like objects

render_engine.feeds module

The Feeds Logic That Makes Up RSS and ATOM FeedTypes.

This is the base files and should only contain the params identified by the standards defined.

RSS: http://www.rssboard.org/rss-specification JSON: https://jsonfeed.org/version/1

class render_engine.feeds.RSSFeed(title, collection)

Bases: render_engine.page.Page

The RSS Feed Component of an Archive Object

engine = <render_engine.feeds.RSSFeedEngine object>
slug = ''
template = 'rss2.0.rss'
class render_engine.feeds.RSSFeedEngine

Bases: render_engine.engine.Engine

The Engine that Processes RSS Feed

environment = <jinja2.environment.Environment object>
extension = '.rss.xml'
class render_engine.feeds.RSSFeedItem(cls)

Bases: object

The Object to be used with an RSS Feed.

title

Title of the post

Type:str
description

Content of the post. Can be the post’s (in order) description, content or summary.

Type:str
guid

unique identifier of the content

Type:str

link to the post. Due to the design of the system, use the reference link and expand to the full link using information from the site

Type:str
pub_date

datetime formatted to RFC 822 (or 2822)

Type:str

render_engine.microblog module

class render_engine.microblog.MicroBlog

Bases: render_engine.blog.Blog

Custom Blog Class pointing to custom templates

content_type

alias of MicroBlogPost

has_archive = True
class render_engine.microblog.MicroBlogPost(**kwargs)

Bases: render_engine.blog.BlogPost

Page Like Object with slight modifications to work with BlogPosts

Attribtues:
title : str
default ‘’. Leave blank.
slug : str
the name for the file for that will
rss_feed_item : RSSFeedItem
the content in an rss format

render_engine.page module

class render_engine.page.Page

Bases: object

Base component used to make web pages.

All components that represent content in HTML, XML, or user-facing JSON generated by Render Engine should be a Page object.

Pages can be rendered directly from a template or generated from a file.

Page objects can be used to extend existing page objects.

Note

Not all attributes are defined by default (those that are marked optional) but will be checked for in other areas of the code.

title

[Optional] title of the Page object

Type:str
engine

[Optional] The engine the Site should use to generate markup. By default this is Jinja2.

Type:str
template

[Optional] template filename for the engine to look for. If defined, it must be a valid file.

Type:str
content_path

[Optional] The filepath to load content from.

The content_path will be checked for additional attributes and base_content.

Raises:FileNotFoundError – If a content_path was supplied path that points to a path that does not exist.

For more information about content paths, markdown and content_path rendering see :ref:<page_from_content_path.rst>

Type:str
base_content

[Optional] Pre-rendered markdown or HTML to be converted to Markup.

Uses the Markdown2 generator.

If content_path is provided the content section of the file will be stored as the base_content

Type:str
list_attrs

list of attributes whose string

Type:typing.Optional[typing.List[str]]
values should be converted

to a comma-delimited list

This is primarily for converting a comma-separated list of values provided in your content_path

Example:

>>> class myPage(Page):
    list_attrs = ["foo"]

# calling myPage will convert the string value of `foo` to a list of values

>>> myPage(foo='my, values, here')
>>> myPage.foo
["my", "values", "here"]
slug

[Optional] The rendered pages filename

A slug passed in will be slugified to ensure a valid path is given. eg. slug="my cool slug" == "my-cool-slug"

If no slug is provided the class name will be used as the slug.:

class MyPage(Page):
    pass

# the path for this page would be https://example.com/mypage
Type:str
always_refresh = False
content
classmethod from_content_path(filepath, **kwargs)
html

Text from self.content converted to html

markdown_extras = ['fenced-code-blocks', 'footnotes']

Plugins to be included when generating HTML from your base_content. Defaults to ["fenced-code-blocks", "footnotes"]

For more information on available extras or creating your own, see the Markdown2 documentation

markup

html = rendered HTML (not marked up). Is None if content == None

matcher = '(^\\w+: \\b.+$)'

Regular expression string to match key/value pairs at the beginning of a content_path.

By default content_path markdown is set to detect markdown metadata format (key: value) with each key/value pair on it’s own line.

In most cases this should not be changed

routes = ['']

the directory in the output_path that the Page should be created at.

Example a route of “pages” for a :py:class render_engine.Page: object with the :py:attr Page.slug: “foo” would generate https://example.com/**pages*/foo*.

An empty string will apply the route at the root https://example.com/foo

url

The first route and the slug of the page.

render_engine.quickstart module

render_engine.quickstart.create_templates_directory(base_dir: str = PosixPath('/home/docs/checkouts/readthedocs.org/user_builds/render-engine/checkouts/latest/docs/source'), templates_dir: str = 'templates', include_template_files: bool = True)

Create Base Folders for your output_dir, static_dir, content_path, and templates_path

render_engine.site module

class render_engine.site.Site

Bases: object

The site stores your pages and collections to be rendered.

Pages are stored in routes and created with site.render(). Collections and subcollections are stored to be used for future use.

Sites also contain global variables that can be applied in templates.

routes

typing.List[typing.Type[Page]] routes are stored prior to being caled with site.render().

SITE_TITLE = 'Untitled Site'

Title for the site. To be used in templates

SITE_URL = 'https://example.com'

Title for the site. To be used in templates

cache_file = PosixPath('.routes_cache')

File that hash id’s will be stored.

The cache_file is checked for values to determine if new pages should be written

default_engine = <render_engine.engine.Engine object>

Engine to generate web pages

get_public_attributes(cls)
output_path = PosixPath('output')

Path to write rendered content.

register_collection(collection_cls: Type[render_engine.collection.Collection]) → None

Add a class to your self.collections iterate through a classes content_path and create a classes Page-like objects, adding each one to routes.

Use a decorator for your defined classes.

Examples:

@register_collection
class Foo(Collection):
    pass
register_feed(feed: render_engine.feeds.RSSFeedEngine, collection: render_engine.collection.Collection) → None

Create a Page object that is an RSS feed and add it to self.routes

register_route(cls: render_engine.page.Page) → None

Create a Page object and add it to self.routes

render(verbose: bool = False, dry_run: bool = False, strict: bool = False) → None
rss_engine = <render_engine.feeds.RSSFeedEngine object>

Engine to generate RSS Feeds

static_path = PosixPath('static')

Top Level Directory for static files.

ALL files in this path will be copied into the output_path.

strict = False

Force all pages to be rebuilt

Module contents