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'¶
-
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.
-
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_contentType: 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 thePage
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 classescontent_path
and create a classesPage
-like objects, adding each one toroutes
.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
-