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>¶

link = ''¶

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¶

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.links module¶

class render_engine.links.Link(name: str, url: str, links: Optional[List[Any]] = None, image: str = '', icon: str = '', alt: str = '')¶

Bases: object

An opinionated format to reference links. Great for creating headers

Look at the example:

myImage = Link(
    name="Render Engine",
    url="https://render-engine.site"
    )

In this case the name and url give you enough information that you can supply to your template:

<a href="{{myImage.url}}">{{myImage.name}}</a>

Any attribute could be applied but here are some that you can supply on initialization.

alt = ''¶

icon = ''¶

image = ''¶

links = None¶

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 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"]

Type:	typing.Optional[typing.List[str]]

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

render_engine package¶

Submodules¶

render_engine.blog module¶

render_engine.collection module¶

render_engine.engine module¶

render_engine.feeds module¶

render_engine.links module¶

render_engine.microblog module¶

render_engine.page module¶

render_engine.quickstart module¶

render_engine.site module¶

Module contents¶