ABlogRelease 0.10.2.dev6

unknown

Dec 24, 2019

CONTENTS

1 Installation 3

2 Getting Started 5

3 How it works 73.1 Blog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83.2 Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.3 Post . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93.4 ablog_build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.5 ablog_clean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103.6 ablog_deploy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.7 ablog_main . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.8 ablog_serve . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.9 PostDirective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.10 PostList . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.11 PostListDirective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.12 PostNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.13 UpdateDirective . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.14 UpdateNode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.15 generate_archive_pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.16 generate_atom_feeds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.17 process_postlist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.18 process_posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143.19 purge_posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.20 register_posts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.21 setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.22 ablog_start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.23 ask_user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.24 generate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.25 ABlog Commands . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163.26 ABlog Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193.27 ABlog Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223.28 ABlog Quick Start . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233.29 ABlog API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253.30 Automate GitHub Pages Deploys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273.31 Cross-referencing Blog Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313.32 Deploy to GitHub Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.33 Draft Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323.34 Jupyter Notebook Posting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333.35 Post Excerpts and Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

i

3.36 Posting and Listing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343.37 Watch Yourself Blogging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.38 ABlog v0.1 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.39 ABlog v0.10 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.40 ABlog v0.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373.41 ABlog v0.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.42 ABlog v0.4 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383.43 ABlog v0.5 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.44 ABlog v0.6 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393.45 ABlog v0.7 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403.46 ABlog v0.8 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 413.47 ABlog v0.9 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.48 ABlog v0.9.1 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.49 ABlog v0.9.2 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423.50 ABlog v0.9.3 released . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Python Module Index 45

Index 47

ii

ABlog, Release 0.10.2.dev6

ABlog is a Sphinx extension that converts any documentation or personal website project into a full-fledged blog with:

• Atom feeds

• Archive pages

• Blog sidebars

• Disqus integration

• Font-Awesome integration

• Easy GitHub Pages deploys

CONTENTS 1

ABlog, Release 0.10.2.dev6

2 CONTENTS

CHAPTER

ONE

INSTALLATION

You can install ABlog using pip:

pip install -U ablog

This will also install Sphinx, Alabaster, Werkzeug, Invoke, dateutil respectively required for building your website,making it look good, generating feeds, running deploy commands, and parsing dates.

3

ABlog, Release 0.10.2.dev6

4 Chapter 1. Installation

CHAPTER

TWO

GETTING STARTED

If you are starting a new project, see ABlog Quick Start guide.

If you already have a project, enable blogging by making following changes in conf.py:

# 1. Add 'ablog' to list of extensionsextensions = [

'...','ablog'

]

# 2. Add ablog templates pathimport ablog

# 2a. if `templates_path` is not definedtemplates_path = [ablog.get_html_templates_path()]

# 2b. if `templates_path` is definedtemplates_path.append(ablog.get_html_templates_path())

5

ABlog, Release 0.10.2.dev6

6 Chapter 2. Getting Started

CHAPTER

THREE

HOW IT WORKS

If you are new to Sphinx and reStructuredText markup language, you might find reStructuredText Primer useful. Onceyou have content (in .rst files), you can post any page using the post directive as follows:

.. post:: Apr 15, 2014:tags: earth, love, peace:category: python:author: me:location: SF:language: en

ABlog will index all files posted as above and list them in archives and feeds specified in :tag:, :category:, etc.options.

You can also include a list of posts using postlist directive:

.. postlist:::list-style: circle:category: Manual:format: {title}:sort:

For ABlog documentation, this converts to the following where you can find more about configuring and using ABlog:

• Posting and Listing

• ABlog Configuration Options

• Cross-referencing Blog Pages

• Post Excerpts and Images

• Posting Sections

• ABlog Internationalization

• ABlog Commands

• ABlog Quick Start

• Deploy to GitHub Pages

• Watch Yourself Blogging

• Automate GitHub Pages Deploys

• ABlog API

• Jupyter Notebook Posting

7

ABlog, Release 0.10.2.dev6

3.1 Blog

class ablog.blog.Blog(app)Bases: collections.abc.Container

Handle blog operations.

Attributes Summary

feed_path RSS feed page name.

Methods Summary

page_id(pagename) Return pagename, trimming index from end whenfound.

page_url(pagename) Return page URL when blog_baseurl is set, oth-erwise None.

recent(num[, docname]) Yield num recent posts, excluding the one with doc-name.

register(docname, info) Register post docname.

Attributes Documentation

feed_pathRSS feed page name.

Methods Documentation

page_id(pagename)Return pagename, trimming index from end when found.

Return value is used as disqus page identifier.

page_url(pagename)Return page URL when blog_baseurl is set, otherwise None.

When found, index.html is trimmed from the end of the URL.

recent(num, docname=None, **labels)Yield num recent posts, excluding the one with docname.

register(docname, info)Register post docname.

8 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.2 Collection

class ablog.blog.Collection(catalog, label, name=None, href=None, path=None, page=0)Bases: ablog.blog.BlogPageMixin

Posts sharing a label, i.e. tag, category, author, or location.

Attributes Summary

catalog Catalog that the collection belongs to.docname Collection page document name.path Collection page document name.

Methods Summary

add(post) Add post to the collection.relsize([maxsize, minsize]) Relative size used in tag clouds.

Attributes Documentation

catalogCatalog that the collection belongs to.

docnameCollection page document name.

pathCollection page document name.

Methods Documentation

add(post)Add post to the collection.

relsize(maxsize=5, minsize=1)Relative size used in tag clouds.

3.3 Post

class ablog.blog.Post(blog, docname, info)Bases: ablog.blog.BlogPageMixin

Handle post metadata.

3.3. Post 9

ABlog, Release 0.10.2.dev6

Attributes Summary

next Next published post in chronological order.prev Previous published post in chronological order.

Methods Summary

to_html(pagename[, fulltext, drop_h1]) Return excerpt or fulltext as HTML after resolvingreferences with respect to pagename.

Attributes Documentation

nextNext published post in chronological order.

prevPrevious published post in chronological order.

Methods Documentation

to_html(pagename, fulltext=False, drop_h1=True)Return excerpt or fulltext as HTML after resolving references with respect to pagename.

By default, first <h1> tag is dropped from the output. More than one can be dropped by setting drop_h1to the desired number of tags to be dropped.

3.4 ablog_build

ablog.commands.ablog_build(builder=None, sourcedir=None, website=None, doctrees=None,traceback=False, runpdb=False, allfiles=False, werror=False,verbosity=0, quiet=False, extra_quiet=False, no_colors=False,**kwargs)

3.5 ablog_clean

ablog.commands.ablog_clean(website=None, doctrees=None, deep=False, **kwargs)

10 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.6 ablog_deploy

ablog.commands.ablog_deploy(website, message=None, github_pages=None, push_quietly=False,push_force=False, github_token=None, github_is_http=True, re-podir=None, **kwargs)

3.7 ablog_main

ablog.commands.ablog_main()Ablog Main.

3.8 ablog_serve

ablog.commands.ablog_serve(website=None, port=8000, view=True, rebuild=False, pat-terns='*.rst;*.txt', **kwargs)

3.9 PostDirective

class ablog.post.PostDirective(name, arguments, options, content, lineno, content_offset,block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Handle post directives.

Attributes Summary

final_argument_whitespacehas_contentoption_specoptional_argumentsrequired_arguments

Methods Summary

run()

3.9. PostDirective 11

ABlog, Release 0.10.2.dev6

Attributes Documentation

final_argument_whitespace = True

has_content = True

option_spec = {'author': <function PostDirective._split>, 'category': <function PostDirective._split>, 'excerpt': <class 'int'>, 'exclude': <function flag>, 'image': <class 'int'>, 'language': <function PostDirective._split>, 'location': <function PostDirective._split>, 'nocomments': <function flag>, 'redirect': <function PostDirective._split>, 'tags': <function PostDirective._split>, 'title': <function PostDirective.<lambda>>}

optional_arguments = 1

required_arguments = 0

Methods Documentation

run()

3.10 PostList

class ablog.post.PostList(rawsource='', *children, **attributes)Bases: docutils.nodes.General, docutils.nodes.Element

Represent postlist directive converted to a list of links.

3.11 PostListDirective

class ablog.post.PostListDirective(name, arguments, options, content, lineno, content_offset,block_text, state, state_machine)

Bases: docutils.parsers.rst.Directive

Handle postlist directives.

Attributes Summary

final_argument_whitespacehas_contentoption_specoptional_argumentsrequired_arguments

Methods Summary

run()

12 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

Attributes Documentation

final_argument_whitespace = False

has_content = False

option_spec = {'author': <function PostListDirective._split>, 'category': <function PostListDirective._split>, 'date': <function PostListDirective.<lambda>>, 'excerpts': <function flag>, 'format': <function PostListDirective.<lambda>>, 'language': <function PostListDirective._split>, 'list-style': <function PostListDirective.<lambda>>, 'location': <function PostListDirective._split>, 'sort': <function flag>, 'tags': <function PostListDirective._split>}

optional_arguments = 1

required_arguments = 0

Methods Documentation

run()

3.12 PostNode

class ablog.post.PostNode(rawsource='', *children, **attributes)Bases: docutils.nodes.Element

Represent post directive content and options in document tree.

3.13 UpdateDirective

class ablog.post.UpdateDirective(name, arguments, options, content, lineno, content_offset,block_text, state, state_machine)

Bases: docutils.parsers.rst.directives.admonitions.BaseAdmonition

Attributes Summary

required_arguments

Methods Summary

run()

3.13. UpdateDirective 13

ABlog, Release 0.10.2.dev6

Attributes Documentation

required_arguments = 1

Methods Documentation

run()

3.14 UpdateNode

class ablog.post.UpdateNode(rawsource='', *children, **attributes)Bases: docutils.nodes.admonition

Represent update directive.

3.15 generate_archive_pages

ablog.post.generate_archive_pages(app)Generate archive pages for all posts, categories, tags, authors, and drafts.

3.16 generate_atom_feeds

ablog.post.generate_atom_feeds(app)Generate archive pages for all posts, categories, tags, authors, and drafts.

3.17 process_postlist

ablog.post.process_postlist(app, doctree, docname)Replace PostList nodes with lists of posts.

Also, register all posts if they have not been registered yet.

3.18 process_posts

ablog.post.process_posts(app, doctree)Process posts and map posted document names to post details in the environment.

14 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.19 purge_posts

ablog.post.purge_posts(app, env, docname)Remove post and reference to it from the standard domain when its document is removed or changed.

3.20 register_posts

ablog.post.register_posts(app)Register posts found in the Sphinx build environment.

3.21 setup

ablog.setup(app)Setup ABlog extension.

3.22 ablog_start

ablog.start.ablog_start(**kwargs)

3.23 ask_user

ablog.start.ask_user(d)Borrowed from Sphinx 1.3b3.

Ask the user for quickstart values missing from d.

Values are:

• path: root path

• project: project name

• author: author names

• version: version of project

• release: release of project

3.24 generate

ablog.start.generate(d, overwrite=True, silent=False)Borrowed from Sphinx 1.3b3.

3.19. purge_posts 15

ABlog, Release 0.10.2.dev6

3.25 ABlog Commands

ablog commands are for streamlining blog operations, i.e. building, serving, and viewing blog pages, as well asstarting a new blog.

$ ablogusage: ablog [-h] [-v] {start,build,clean,serve,post,deploy} ...

ABlog for blogging with Sphinx

optional arguments:-h, --help show this help message and exit-v, --version print ABlog version and exit

subcommands:{start,build,clean,serve,post,deploy}start start a new blog projectbuild build your blog projectclean clean your blog build filesserve serve and view your projectpost create a blank postdeploy deploy your website build files

See 'ablog <command> -h' for more information on a specific command.

Here are all the things you can do:

• Start a New Project

• Build your Website

• Serve and View Locally

• Deploy to GitHub Pages

• Create a Post

• Clean Build Files

3.25.1 Start a New Project

ablog start command is for quickly setting up a blog project. See ABlog Quick Start for how it works and whatit prepares for you.

$ ablog start -husage: ablog start [-h]

Start a new blog project by answering a few questions. You will end up with aconfiguration file and sample pages.

optional arguments:-h, --help show this help message and exit

16 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.25.2 Build your Website

Running ablog build in your project folder builds your website HTML pages.

$ ablog build -husage: ablog build [-h] [-a] [-b BUILDER] [-s SOURCEDIR] [-w WEBSITE]

[-d DOCTREES] [-T] [-P]

Path options can be set in conf.py. Default values of paths are relative toconf.py.

optional arguments:-h, --help show this help message and exit-a write all files; default is to only write new and changed

files-b BUILDER builder to use, default `ablog_builder` or dirhtml-s SOURCEDIR root path for source files, default is path to the folder that

contains conf.py-w WEBSITE path for website, default is _website when `ablog_website` is

not set in conf.py-d DOCTREES path for the cached environment and doctree files, default

.doctrees when `ablog_doctrees` is not set in conf.py-T show full traceback on exception-P run pdb on exception

3.25.3 Serve and View Locally

Running ablog serve, after building your website, will start a Python server and open up browser tab to view yourwebsite.

$ ablog serve -husage: ablog serve [-h] [-w WEBSITE] [-p PORT] [-n] [-r] [--patterns]

Serve options can be set in conf.py. Default values of paths are relative toconf.py.

optional arguments:-h, --help show this help message and exit-w WEBSITE path for website, default is _website when `ablog_website` is

not set in conf.py-p PORT port number for HTTP server; default is 8000-n do not open website in a new browser tab-r rebuild when a file matching patterns change or get added--patterns patterns for triggering rebuilds

3.25. ABlog Commands 17

ABlog, Release 0.10.2.dev6

3.25.4 Deploy to GitHub Pages

Running ablog deploy will push your website to GitHub.

$ ablog deploy -husage: ablog deploy [-h] [-w WEBSITE] [-p REPODIR] [-g GITHUB_PAGES]

[-m MESSAGE] [-f] [--push-quietly][--github-token GITHUB_TOKEN]

Path options can be set in conf.py. Default values of paths are relative toconf.py.

optional arguments:-h, --help show this help message and exit-w WEBSITE path for website, default is _website when

`ablog_website` is not set in conf.py-p REPODIR path to the location of repository to be deployed,

e.g. `../username.github.io`, default is foldercontaining `conf.py`

-g GITHUB_PAGES GitHub username for deploying to GitHub pages-m MESSAGE commit message-f owerwrite last commit, i.e. `commit --amend; push -f`--push-quietly be more quiet when pushing changes--github-token GITHUB_TOKEN

environment variable name storing GitHub access token

3.25.5 Create a Post

Finally, ablog post will make a new post template file.

$ ablog post -husage: ablog post [-h] [-t TITLE] filename

positional arguments:filename filename, e.g. my-nth-post (.rst appended)

optional arguments:-h, --help show this help message and exit-t TITLE post title; default is formed from filename

3.25.6 Clean Build Files

In case you needed, running ablog clean will remove build files and do a deep clean with -D option.

$ ablog clean -husage: ablog clean [-h] [-d DOCTREES] [-w WEBSITE] [-D]

Path options can be set in conf.py. Default values of paths are relative toconf.py.

optional arguments:-h, --help show this help message and exit-d DOCTREES path for the cached environment and doctree files, default

.doctrees when `ablog_doctrees` is not set in conf.py

(continues on next page)

18 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

(continued from previous page)

-w WEBSITE path for website, default is _website when `ablog_website` isnot set in conf.py

-D deep clean, remove cached environment and doctree files

Updated on 07 April 2015

Added ablog clean and ablog deploy commands.

3.26 ABlog Configuration Options

This post describes ABlog configuration options that go in Sphinx build configuration file.

3.26.1 General options

blog_pathA path relative to the configuration directory for blog archive pages. Default is 'blog'.

blog_titleThe “title” for the blog, used in acthive pages. Default is 'Blog'.

blog_baseurlBase URL for the website, required for generating feeds.

blog_archive_titlesChoose to archive only post titles in collection pages, default is False.

3.26.2 Authors, languages, & locations

blog_authorsA dictionary of author names mapping to author full display names and links. Dictionary keys are what shouldbe used in post directive to refer to the author. Default is {}. Example:

blog_authors = {'Ahmet': ('Ahmet Bakan', 'http://ahmetbakan.com'),'Durden': ('Tyler Durden',

'https://en.wikipedia.org/wiki/Tyler_Durden'),}

blog_languagesA dictionary of language code names mapping to full display names and links of these languages. Similar toblog_authors, dictionary keys should be used in post directive to refer to the locations. Default is {}.Example:

blog_languages = {'en': ('English', None),

}

blog_locationsA dictionary of location names mapping to full display names and links of these locations. Similar toblog_authors, dictionary keys should be used in post directive to refer to the locations. Default is {}.

3.26. ABlog Configuration Options 19

ABlog, Release 0.10.2.dev6

blog_default_authorName of the default author defined in blog_authors. Default is None.

blog_default_languageCode name of the default language defined in blog_languages. Default is None.

blog_default_locationName of the default location defined in blog_locations. Default is None.

Updated on 15 September 2014

Added blog_languages and blog_default_language configuration variables.

3.26.3 Post related

post_date_formatDate display format (default is '%b %d, %Y') for published posts that goes as input to datetime.date.strftime().

post_auto_excerptNumber of paragraphs (default is 1) that will be displayed as an excerpt from the post. Setting this 0 will resultin displaying no post excerpt in archive pages. This option can be set on a per post basis using post directiveoption excerpt.

See Post Excerpts and Images for a more detailed discussion.

post_auto_imageIndex of the image that will be displayed in the excerpt of the post. Default is 0, meaning no image. Setting thisto 1 will include the first image, when available, to the excerpt. This option can be set on a per post basis usingpost directive option image.

post_redirect_refreshNumber of seconds (default is 5) that a redirect page waits before refreshing the page to redirect to the post.

post_always_sectionWhen True, post title and excerpt is always taken from the section that contains the post directive, instead ofthe document. This is the behavior when post is used multiple times in a document. Default is False.

3.26.4 Blog feeds

Turn feeds on by setting blog_baseurl configuration variable.

blog_feed_archivesChoose to create feeds per author, location, tag, category, and year, default is False.

blog_feed_fulltextChoose to display full text in blog feeds, default is False.

blog_feed_subtitleBlog feed subtitle, default is None.

blog_feed_titlesChoose to feed only post titles, default is False.

blog_feed_lengthSpecify number of recent posts to include in feeds, default is None for all posts.

20 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

Updated on 24 August 2014

Added blog_feed_archives, blog_feed_fulltext, blog_feed_subtitle, andpost_always_section options.

Updated on 27 November 2014

Added blog_feed_titles, blog_feed_length, and blog_archive_titles options.

3.26.5 Font awesome

ABlog templates will use of Font Awesome icons if one of the following is set:

fontawesome_link_cdnURL to Font Awesome .css hosted at Bootstrap CDN or anywhere else. Default: None

Updated on 29 July 2015

fontawesome_link_cdn was a boolean option, and now became a string to enable using desired version of FontAwesome. To get the old behavior, use ‘https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.min.css'.

fontawesome_includedSphinx theme already links to Font Awesome. Default: False

Alternatively, you can provide the path to Font Awesome .css with the following configuration option:

fontawesome_css_filePath to Font Awesome .css (default is None) that will be linked to in HTML output by ABlog.

3.26.6 Disqus integration

Of course one cannot think of a blog that doesn’t allow for visitors to comment. You can enable Disqus by settingdisqus_shortname and blog_baseurl variables. The reason for requiring blog_baseurl to be specifiedas of v0.7.2 is to ensure that Disqus associates correct URLs with threads when you serve new posts locally for thefirst time.

disqus_shortnameDisqus short name for the website.

disqus_pagesChoose to disqus pages that are not posts, default is False.

disqus_draftsChoose to disqus posts that are drafts (without a published date), default is False.

3.26. ABlog Configuration Options 21

ABlog, Release 0.10.2.dev6

3.26.7 Blog sidebars

Finally, there are seven sidebars you can include in your HTML output using Sphinx html_sidebars configurationoption. Sidebars that you see on the left are listed below in the same order:

html_sidebars = {'**': [...,

'postcard.html', 'recentposts.html','tagcloud.html', 'categories.html','archives.html', ]

}

postcard.html provides information regarding the current post. recentposts.html lists most recent fiveposts. Others provide a link to a archive pages generated for each tag, category, and year. In addition, there areauthors.html, languages.html, and locations.html sidebars that link to author and location archivepages.

3.26.8 Command Options

Updated on 07 April 2015

Added ABlog Commands options.

ablog_websiteDirectory name for build output files. Default is _website.

ablog_doctreesDirectory name for build cache files. Default is .doctrees.

ablog_builderHTML builder, default is dirhtml. Build HTML pages, but with a single directory per document. Makes forprettier URLs (no .html) if served from a webserver. Alternative is html to build one HTML file per document.

github_pagesGitHub user name used by ablog deploy command. See Deploy to GitHub Pages and Deploy to GitHubPages for more information.

3.27 ABlog Internationalization

ABlog automatically generates certain labels like Posts and Categories. If these labels appear in English on your blogalthough you specified another language, then this page is for you.

ABlog needs your help for translation of these labels. Translation process involves the following steps:

1. Update translatable messages:

Execute extract_messages each time a translatable message text is changed or added:

$ python setup.py extract_messages -o ablog/locale/sphinx.pot...

This will create or update ablog/locale/sphinx.pot file, the central messages catalog used by the dif-ferent translations.

22 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

2. a. Create new translation catalog:

Execute init_catalog once for each new language, e.g.:

$ python setup.py init_catalog -l de -i ablog/locale/sphinx.pot -o ablog/→˓locale/de/LC_MESSAGES/sphinx.po

This will create a file ablog/locale/de/LC_MESSAGES/sphinx.po in which translations needsto be placed.

b. Update translation catalog:

Execute update_catalog for each existing language, e.g.:

$ python setup.py update_catalog -l de -i ablog/locale/sphinx.pot -o ablog/→˓locale/de/LC_MESSAGES/sphinx.po

This will update file ablog/locale/de/LC_MESSAGES/sphinx.powhere translations of new textneeds to be placed.

3. Compile catalogs:

Execute compile_catalog for each existing language, e.g.:

$ python setup.py compile_catalog --directory ablog/locale/ --domain sphinx --→˓locale de

3.28 ABlog Quick Start

This short walk through of blogging work flow assumes that you have already installed ABlog. If not, see Installationguide.

Note that this post is a working draft. Feel free to revise it on GitHub.

3.28.1 Start a Project

To start a new project, run ablog start command in a directory where you want to keep your project source files.This command will ask you a few questions and create the following files:

• conf.py that contains project configuration for building HTML pages.

• first-post.rst, a blog post example.

• index.rst that contains content for the landing page of your website.

• about.rst, another non-post page example.

3.28. ABlog Quick Start 23

ABlog, Release 0.10.2.dev6

3.28.2 Build and View

With no further delay, let’s see what your project will look like. First run ablog build, in your project folder, tohave HTML pages built in _website folder. Then, call ablog serve to view them in your default web browser.See ABlog Commands for more information about these commands.

Your landing page is built from index.rst and contains links to your first post and about page. Take a look atindex.rst for some tips on navigation links within the project.

3.28.3 Write Content

If you are new to Sphinx and reStructuredText markup language, you might find reStructuredText Primer useful.

Pages

Pages in your project are .rst files that are only a post directive short of becoming blog posts. To make regularpages accessible from the navigation bar, you need to list them in a toctree. This is shown for about page intoindex.rst.

Posts

You can convert any page to a post with a post directive. ABlog will take care of listing posts in specified archivesand sidebars.

3.28.4 Comments

You can enable comments in your website by creating a Disqus account and obtaining a unique identifier, i.e.disqus_shortname. See Disqus integration for configuration options.

3.28.5 Analytics

ABlog uses Alabaster theme by default. You can use theme options to set your Google Analytics identifier to enabletracking.

3.28.6 Configuration

There are four major groups of configuration options that can help you customize how your website looks:

• ABlog Configuration Options - add blog authors, post locations and languages to your blog, adjust archive andfeed content, etc.

• General configuration and project information

• Options for HTML output - configure appearance of your website

• Alabaster theme options - link to your GitHub account and project, set up tracking, etc.

24 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.28.7 Other Folders

You might have noticed that your project contains three folders that we have not mention yet. Here they are:

• _static is for keeping image, .js, and .css files. html_static_path Sphinx option for more infor-mation.

• _templates is for custom HTML templates. See templates_path for more information.

• .doctree folder, created after build command is called, is where Sphinx stores the state of your project. Filesin this folder saves time when you rebuild your project.

3.29 ABlog API

3.29.1 ablog Package

Functions

setup(app) Setup ABlog extension.

3.29.2 ablog.blog Module

Classes

Blog(app) Handle blog operations.Post(blog, docname, info) Handle post metadata.Collection(catalog, label[, name, href, . . . ]) Posts sharing a label, i.e.

Class Inheritance Diagram

BlogContainer

BlogPageMixin

Collection

Post

3.29. ABlog API 25

ABlog, Release 0.10.2.dev6

3.29.3 ablog.commands Module

Functions

ablog_build([builder, sourcedir, website, . . . ])ablog_clean([website, doctrees, deep])ablog_serve([website, port, view, rebuild, . . . ])ablog_deploy(website[, message, . . . ])ablog_main() Ablog Main.

3.29.4 ablog.post Module

Functions

purge_posts(app, env, docname) Remove post and reference to it from the standard do-main when its document is removed or changed.

process_posts(app, doctree) Process posts and map posted document names to postdetails in the environment.

process_postlist(app, doctree, docname) Replace PostList nodes with lists of posts.generate_archive_pages(app) Generate archive pages for all posts, categories, tags,

authors, and drafts.generate_atom_feeds(app) Generate archive pages for all posts, categories, tags,

authors, and drafts.register_posts(app) Register posts found in the Sphinx build environment.

Classes

PostNode([rawsource]) Represent post directive content and options in docu-ment tree.

PostList([rawsource]) Represent postlist directive converted to a list oflinks.

UpdateNode([rawsource]) Represent update directive.PostDirective(name, arguments, options, . . . ) Handle post directives.UpdateDirective(name, arguments, options, . . . )PostListDirective(name, arguments, options,. . . )

Handle postlist directives.

26 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

Class Inheritance Diagram

Admonition admonition

Body

General

BaseAdmonition UpdateDirective

Directive PostDirective

PostListDirective

Element

PostList

PostNodeNode

UpdateNode

3.29.5 ablog.start Module

Functions

generate(d[, overwrite, silent]) Borrowed from Sphinx 1.3b3.ask_user(d) Borrowed from Sphinx 1.3b3.ablog_start(**kwargs)

3.30 Automate GitHub Pages Deploys

If being away from your personal computer is holding you back from blogging, keep reading. This post will show youhow to automate builds and deploys using Travis CI. Once you set this up, all you need to do post an article will bepushing to GitHub or creating a new file on GitHub.com from any computer!

For this to work, you need to be hosting your website on GitHub pages. If you are not already doing so, see Deploy toGitHub Pages.

3.30. Automate GitHub Pages Deploys 27

ABlog, Release 0.10.2.dev6

3.30.1 Signup for Travis CI

Travis CI is a continuous integration service used to build and test projects hosted at GitHub. You can easily sync yourGitHub projects with Travis CI signing up for Travis CI using your GitHub account:

Once you login, go to Accounts page and flick the switch on for your source repository for GitHub pages. In the belowexample, website is the source repository and sunpy.github.io contains HTML output from builds:

28 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.30.2 Deploy key setup

To have builds pushed from Travis CI to GitHub, you will need a personal access token. Go to GitHub Settings →Personal access tokens page to generate a new token. You need only public repo access checked for this purpose:

Then, you need to set this access token as an environment variable, e.g. DEPLOY_KEY, under Settings → EnvironmentVariables. Keep the :guilabel:Display value in build logs` switch off.

Also, do not forget to flick Build pushes on under Settings → General Settings:

3.30.3 Configuration file

Finally, you need a .travis.yml in your project that looks like the following:

language: python

python:- 2.7

virtualenv:system_site_packages: true

before_install:- pip install ablog

script:- ablog build

after_success:- git config --global user.name "Your Name"

(continues on next page)

3.30. Automate GitHub Pages Deploys 29

ABlog, Release 0.10.2.dev6

30 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

(continued from previous page)

- git config --global user.email "yourname@domain.com"- git config --global push.default simple- ablog deploy --push-quietly --github-token=DEPLOY_KEY -m="`git log -1 --pretty=%B`

→˓"

The main part of the process, that is building of the website, is under script block. If you repository has dependen-cies to other Python packages, you can install them in before_install block.

Upon a successful built, your website is deployed. Note that there is no mention of your GitHub Pages repository, i.e.username.github.io. That is specified in conf.py file with github_pages. See Deploy to GitHub Pagesand ABlog Commands to find out more about deploy options.

Finally, you can find out more about .travis.yml file and customizing your built on Travis CI user documentation.

3.31 Cross-referencing Blog Pages

ABlog creates references to all post and archive pages. Posts can be cross-referenced using the name of the file, orwhen the file is named index, the name of the folder that contains the file.

This page, Cross-referencing Blog Pages, for example is referenced as :ref:`cross-referencing-blog-pages` using ref role.

When posts have long file names, it may be inconvenient to use them repeatedly for cross-referencing. An alternativethat Sphinx offers is creating your own short and unique labels for cross-referencing to posts. See Cross-referencingsyntax for details.

3.31.1 Archive pages

Archive pages, on the other hand, can be cross-referenced by combining archive type and archive name as follows:

Archive Example reStructured TextPosts Posts :ref:`blog-posts`Drafts Drafts :ref:`blog-drafts`Author Ahmet Bakan :ref:`author-ahmet`Language English :ref:`language-en`Location Pittsburgh, PA :ref:`location-pittsburgh`

Following archive pages list all posts by grouping them:

Archive Example reStructured TextBy tag Tags :ref:`blog-tags`By author Authors :ref:`blog-authors`By language Languages :ref:`blog-languages`By location Locations :ref:`blog-locations`By category Categories :ref:`blog-categories`By archive Archives :ref:`blog-archives`

3.31. Cross-referencing Blog Pages 31

ABlog, Release 0.10.2.dev6

3.32 Deploy to GitHub Pages

If you are looking for a place to publish your blog, GitHub Pages might be the place for you.

Assuming that you have a GitHub account, here are what you need to do to get published:

1. Head over to GitHub and create a new repository named username.github.io, where username is yourusername (or organization name) on GitHub.

2. (optional) If you followed the link, you might as well give a star to ABlog ;)

3. Set github_pages configuration variable in conf.py file.

4. Run ablog build in your project folder.

5. Run ablog deploy. This command will

i. clone your GitHub pages repository to project folder,

ii. copy all files from build folder (_website) to username.github.io,

iii. add and commit copied files,

iv. add .nojekyll file, since this ain’t no Jekyll

v. and finally push the changes to publish.

Let us know how this works for you!

3.33 Draft Example

As the title suggests, this is a draft example and shall remain so until the end of time or internet.

3.33.1 How do you draft a post?

Just indicate that the page is a post using post directive, but do not provide give a published date:

.. post:::tags: draft:category: Manual

You can still label a post you are drafting with tags and categories, but the post will not be listed in correspondingarchive pages until it is published.

3.33.2 How can you see a list of drafts?

See Drafts archive page, which can be referred to as :ref:blog-drafs`.

32 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.33.3 Why would you make a post draft?

Let’s say you are using Disqus on your website, and allowing non-post pages to be discussed as well, but you don’twant a draft to be discussed before it is published. By adding post directive without published date and keepingconfiguration variable disqus_drafts as False, you can achieve that.

3.34 Jupyter Notebook Posting

To add support for Notebooks to your Ablog instance, you need to configure your docs/conf.py (or whereeveryour conf.py is located.

You will need to add

extennsions = [..., 'nbsphinx', ...]exclude_patterns = ['docs/manual/.ipynb_checkpoints/*'] (To exclude the notebook→˓autosaves)

You will need to install nbsphinx either from Anaconda or pip. You might need to install ipython to make sure thenotebook can be run.

Within the notebook you need to make sure the cells are in this order: Titlte cell, post cell. So for this notebook, it

looks like this:

So the information is similar to how you create a normal RST post.

Another working example is SunPy’s website which runs Ablog. The Pull Request that added support can be foundhere and how to link them to a Binder instance here.

3.35 Post Excerpts and Images

3.35.1 Excerpts

ABlog, by default, uses first paragraph of the document as post excerpt. Default number of paragraphs to use inexcerpts is controlled via post_auto_excerpt configuration variable. This option can be overwritten using :excerpt: option in post directive.

Alternatively, you can provide some content in a post directive as follows:

.. post:: Apr 15, 2014

This is all of the excerpt for this post.

This content is going to be used as excerpt in archive pages. Furthermore, if you do not want the excerpt to be includedin the post, you can use :exclude: option as follows:

3.34. Jupyter Notebook Posting 33

ABlog, Release 0.10.2.dev6

.. post:: Apr 15, 2014:exclude:

This is all of the excerpt for this post. It will be displayedin archive pages and excluded from the post page.

3.35.2 Images

Let’s first include a local and a non-local image in this post.

To link the second one of these, we add :image: 2 option in post directive.

3.36 Posting and Listing

This post describes post, update, and postlist directives.

3.36.1 Posting

Any page in a Sphinx project can be converted to a post using the following directive:

.. post::All possible directive options are shown below:

.. post:: 15 Apr, 2013:tags: tips, ablog, directive:category: Example, How To:author: Ahmet, Durden:location: Pittsburgh, SF:redirect: blog/old-page-name-for-the-post:excerpt: 2:image: 1:nocomments:

Drafts & Posts

Posts without dates or with future dates are considered as drafts and are published only in Drafts archive page.

Posts with dates that are older than the day Sphinx project is built are published in Posts page.

Post date format must follow the format specified with post_date_format configuration option.

Tags & Categories

34 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

You can specify multiple tags and categories by separating them with commas. Posts will be listed in archivepages generated for each unique tag and category.

Authors, Languages, & Locations

Likewise, you can specify authors, languages, and locations of a post using :author:, :language:, and:location: options. All of these option names are in their singular form, but multiple values separated bycommas are accepted.

Using blog_authors, blog_languages, and blog_locations configuration variables, you can alsoprovide home pages and/or full display names of authors, languages, and locations, which will be displayed inarchive pages generated for all unique authors, languages, and locations.

Redirections

You can make ABlog create pages that will redirect to current post using :redirect: option. It takes a commaseparated list of paths, relative to the root folder. The redirect page waits for post_redirect_refreshseconds before redirection occurs.

Disable comments

You can disable comments for the current post using the :nocomments: option. Currently there is no way todisable comments in a specific page.

Excerpts & Images

By default, ABlog uses the first paragraph of a page as post excerpt. You can change this behavior and also addan image to the excerpt. To find out how, see Post Excerpts and Images.

Update Notes

.. update::Update in a post can be noted anywhere in the post as follows:

.. update:: 20 Apr, 2014

Added :rst:dir:`update` directive and :ref:`posting-sections`section. Also revised the text here and there.

Update date format must follow the format specified with post_date_format configuration option.

Update directive renders like the updates that are at the end of this post.

3.36.2 Posting Sections

post directive can be used multiple times in a single page to create multiple posts of different sections of the docu-ment.

When post is used more than once, post titles and excerpts are extracted from the sections that contain the directives.This behavior can also be set as the default behavior using post_always_section configuration options.

Some caveats and differences from posting a document once are:

• Next and previous links at the bottom will only regard the first post in the document.

• Information displayed on the sidebar will belong to the first post.

• References for section posts is not automatically created. Labels for cross-referencing needs to be createdmanually, e.g. .. _posting-sections. See Cross-referencing syntax for details.

Multiple use of post may be suitable for major additions to a previous post. For minor changes, update directivemay be preferred.

3.36. Posting and Listing 35

ABlog, Release 0.10.2.dev6

3.36.3 Listing

A list of posts can be displayed in any page using the following directive:

.. postlist::

Following example display all the options the directive takes:

.. postlist:: 5:author: Ahmet:category: Manual:location: Pittsburgh:language: en:tags: tips:date: %A, %B %d, %Y:format: {title} by {author} on {date}:list-style: circle:excerpts::sort:

This will result in a bullet list of up to 5 posts (default is all) authored by :ref:`author-ahmet` in :ref:`language-en` when he was in :ref:`location-pittsburgh` and posted in :ref:`category-manual` with tags :ref:`tag-tips`.Posts will be in :sort:ed to appear in chronological order and listed with their :excerpts:. Here are thoseposts:

• Cross-referencing Blog Pages by Ahmet Bakan on Sunday, May 11, 2014

ABlog creates references to all post and archive pages. Posts can be cross-referenced using the name ofthe file, or when the file is named index, the name of the folder that contains the file.

When no options are given all posts will be considered and they will be ordered by recency. Also, note that ifthe current post is one of the most recent posts, it will be omitted.

Updated on 20 August 2014

Added update directive and Posting Sections section. Also revised the text here and there.

Updated on 15 September 2014

• post directive has :language: option.

• postlist directive takes arguments to filter posts.

Updated on 28 March 2015

Added :excerpts: option to postlist to list posts with their excerpts.

Updated on 14 April 2015

Added :list-style: option to postlist to control bullet list style. circle, disk, and none (default) are recog-nized.

36 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.37 Watch Yourself Blogging

Wouldn’t you like your blog being rebuilt and served to you automatically as you are blogging on a sunny Sundayafternoon? It’s now possible with the improved ablog serve command.

First, you need to install Watchdog Python package, e.g. pip install watchdog. Then, you need to run ablog serve-r. Regardless of the weather being sunny or the day of the week, your project will be rebuilt when you change apage or add a new one. This won’t refresh your browser page though. Unless you want to hit refresh once in a while,you can easily find an auto refresher extension for you browser.

3.38 ABlog v0.1 released

ABlog v0.1 is released.

This is the very first release, so there are no release notes in this post.

Yes, this page is also a post and it resides in a folder different from most other posts in this blogumentation.

The idea is to enable making any page in a Sphinx project a post so that users of a software package can subscribe tofeeds and follow new releases as well as code examples added to the documentation.

3.39 ABlog v0.10 released

ABlog v0.10 is released with the main focus being to support the latest version of Sphinx as well as Python 3 onlysupport.

Ablog V0.9.X will no longer be supported as Python 2 comes to an end in a few months and it is time people upgraded.

Pull Requests Merged in:

Overhaul of package underneath for python3 only from nabobalis.

Add validation for conf.py entries from rayalan.

Deploy improve from rayalan.

Get ablog ready for 0.10 from nabobalis.

3.40 ABlog v0.2 released

ABlog v0.2 is released. This version comes with several new features:

• You can post a document multiple times, see Posting Sections for details.

• You can make note of updates in a post using update directive.

• Blog feeds for authors, locations, categories, tags, and years can be enabled using blog_feed_archivesconfiguration variable.

• Blog Feeds can be made full text using blog_feed_fulltext configuration variable.

• Recent posts side bar includes month and day of the posts.

3.37. Watch Yourself Blogging 37

ABlog, Release 0.10.2.dev6

3.40.1 ABlog v0.2.1 released

ABlog v0.2.1 is a bug fix release that solves duplicated content problem in full text atom feeds.

3.40.2 ABlog v0.2.2 released

ABlog v0.2.2 is a bug fix release that solves broken links problem in post lists (issue 12).

3.40.3 ABlog v0.2.3 released

ABlog v0.2.3 is a bug fix release that solves broken links (issue 13) and non-unique post IDs problems atom feeds.

3.41 ABlog v0.3 released

ABlog v0.3 is released. This version comes with the following core improvements:

• You can now specify language of a post with :language: option, and an archive page will be created foreach language. See blog_languages and blog_default_language if you are posting in multiplelanguages.

• You can list language archives on your website by adding languages.html to html_sidebars configu-ration option.

• postlist directive takes options to filter posts.

3.41.1 ABlog v0.3.1 released

ABlog v0.3.1 is a minor release to fix two issues in templates:

• Links to collection (archive) feeds is displayed only on collection page (e.g. :ref:`category-manual`), not on acatalog page that lists posts for multiple collections (e.g. :ref:`blog-categories`).

• Links to collection feeds is displayed only when they are generated (see blog_feed_archives). Previously,links would be generated to feeds that did not exist.

3.42 ABlog v0.4 released

ABlog v0.4 is released. This version comes with the following improvements and bug fixes:

• Added blog_feed_titles, blog_feed_length, and blog_archive_titles configuration op-tions (see issue 24).

• Set the default for blog_feed_archives to False, which was set to True although documented to beotherwise.

• Fixed issues with post_auto_excerpt and post_auto_image configuration options.

• Fixed issue 2, relative size of tags being the minimum size when all tags have the same number of posts. Now,mean size is used, and max/min size can be controlled from template.

• Fixed issue 19. Yearly archives are ordered by recency.

• Fixed duplicated post title in feeds, issue 21.

38 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

• Fixed issue 22, postlist directive listing more than specified number of posts.

• postlist directive accepts arguments to format list items (issue 20).

3.43 ABlog v0.5 released

ABlog v0.5 is released. This version comes with ABlog Commands and a ABlog Quick Start guide.

3.43.1 ABlog v0.5.1 released

Added :excerpts: option to postlist directive.

3.44 ABlog v0.6 released

ABlog v0.6 is released with new ABlog Commands. You can use ablog deploy to Deploy to GitHub Pages, andalso ablog clean to do spring cleaning every once in a while.

3.44.1 ABlog v0.6.1 released

ABlog v0.6.1 is released with improvements to ablog deploy command. It will add .nojekyll file whenneeded to deployments to GitHub pages.

3.44.2 ABlog v0.6.2 released

ABlog v0.6.2 is released to fix an issue with loading of Disqus comments (issue 33) and interpreting non-ascii char-acters (issue 34).

3.44.3 ABlog v0.6.3 released

ABlog v0.6.3 comes with Russian localisation and following enhancements:

• Added :list-style: option to postlist to enable controlling bullet list style.

• ablog post command de-slugifies filename to make the title when it’s not given.

3.44.4 ABlog v0.6.4 released

ABlog v0.6.4 comes with improved ablog serve command that helps you Watch Yourself Blogging.

3.43. ABlog v0.5 released 39

ABlog, Release 0.10.2.dev6

3.44.5 ABlog v0.6.5 released

ABlog v0.6.5 is a bug fix release to resolve issue 38, an exception raised when using postlist without specifyingnumber of posts.

3.45 ABlog v0.7 released

ABlog v0.7.0 is released to fix the long standing issue 1 related to pickling of Sphinx build environment on Read TheDocs. Improvements also resolved issues with using LaTeX builder, improved cross-referencing for non-html builders.

3.45.1 ABlog v0.7.1 released

ABlog v0.7.1 is released to fix Python 3 import issues in ablog serve command.

3.45.2 ABlog v0.7.2 released

ABlog v0.7.2 is released to prevent potential issues with Disqus thread URLs by requiring disqus_shortnameand blog_baseurl to be specified together for Disqus integration.

3.45.3 ABlog v0.7.3 released

ABlog v0.7.3 makes use of python-dateutil for parsing post dates, so now you can be flexible with the format you usein posts. Thanks to Andy Maloney for this improvement.

3.45.4 ABlog v0.7.5 released

ABlog v0.7.5 is released to fix Windows specific path resolving issue with archive pages. Thanks to Peter Mills forreporting this issue.

3.45.5 ABlog v0.7.6 released

ABlog v0.7.6 is released to fix path resolving issue that arose when :excerpts: is used in postlist directive.Once again, thanks to Peter Mills for reporting this issue. Other minor changes are:

• -P argument is added to ablog build command to enable running pdb on exceptions.

• conf.py file created by ablog start updated to include about.html sidebar that comes with Alabastertheme.

40 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.45.6 ABlog v0.7.7 released

ABlog v0.7.7 is released to fix path resolving issue 41 that arose when cross-references were used in post excerpts,and also post redirect issue in templates.

3.45.7 ABlog v0.7.8 released

ABlog v0.7.8 is released to fix a Python 2 issue that appears when creating collection pages that contain non-ascii char-acters in their names (issue 45) and filename escaping issue when committing changes using ablog deploy command(pull request 44). Thanks to uralbash for these contributions.

3.45.8 ABlog v0.7.9 released

ABlog v0.7.9 is released to fix Windows specific file renaming issue in ablog deploy command (issue 46). Thanks toVelimir for the fix.

3.45.9 ABlog v0.7.10 released

ABlog v0.7.10 is released to resolve Sphinx JSON/Pickle builder issues related to serialization.

3.45.10 ABlog v0.7.12 released

ABlog v0.7.12 (and also v0.7.11) maintenance release are available.

3.46 ABlog v0.8 released

ABlog v0.8.0 is released with additions and changes:

• Added -a argument to ablog build command, with which you can force rewriting all pages when rebuildingyour project. Default is writing only pages that have changed.

• Added -f argument to ablog deploy command, with which you can amend to latest commit to keep GitHubpages repository small. Thanks to uralbash for this contribution.

• Added -p argument to ablog deploy command, with which you can specify the path to your GitHub pagesrepository, i.e. username.github.io.

• Changed fontawesome_link_cdn to be a string argument to enable linking to desired version of FontAwesome. Thanks to Albert Mietus for this contribution.

• Post lists font style is now controlled through CSS. Thanks to Albert Mietus for this contribution as well.

• Fixed internal link resolution issue that affected atom feeds of collections, i.e. feeds of posts under a category,tag, or author.

3.46. ABlog v0.8 released 41

ABlog, Release 0.10.2.dev6

3.46.1 ABlog v0.8.1 released

ABlog v0.8.1 is released to fix atom feed linking in HTML header (issue 54).

3.46.2 ABlog v0.8.2 released

ABlog v0.8.2 is released to fix date parsing (issue 58) and Python 2.6 installation (issue 59) issues.

3.46.3 ABlog v0.8.3 released

ABlog v0.8.3 is released to bring you recent enhancements:

• ninmesara added :nocomments: argument to post directive to disable comments per post.

• José Carlos García added Spanish translations.

3.47 ABlog v0.9 released

ABlog v0.9.0 is released with the main focus being to support the latest version of Sphinx. This also moves the maindevelopment from Abakan to SunPy.

This has merged in all current (at time of writing, 6) open PRs to the original repository.

These are:

fix(commands): Update command arguments so patterns works correctly from rayalan.

Fix couple of bugs with latest stable Sphinx from tadeboro.

don’t use fancy quotes in the conf.py template from tiwo.

Pass through additional Sphinx options and fix a typo from ahrbel.

fix #78 (ImportError: cannot import name make_admonition in Sphinx 1.6) from lsaffre.

Raise exception when title is missing from rgrinberg.

3.48 ABlog v0.9.1 released

Minor update to remove Ablog{}.format(python_number) exes

3.49 ABlog v0.9.2 released

Fixed Windows String issue

42 Chapter 3. How it works

ABlog, Release 0.10.2.dev6

3.50 ABlog v0.9.3 released

Added example on how to use writing blog posts in Jupyter notebooks. Several fixes provived by anzawatta, sorry Iwas late to release these!

3.50. ABlog v0.9.3 released 43

ABlog, Release 0.10.2.dev6

44 Chapter 3. How it works

PYTHON MODULE INDEX

aablog, 25ablog.blog, 25ablog.commands, 26ablog.post, 26ablog.start, 27

45

ABlog, Release 0.10.2.dev6

46 Python Module Index

INDEX

Aablog (module), 25ablog.blog (module), 25ablog.commands (module), 26ablog.post (module), 26ablog.start (module), 27ablog_build() (in module ablog.commands), 10ablog_builder

configuration value, 22ablog_clean() (in module ablog.commands), 10ablog_deploy() (in module ablog.commands), 11ablog_doctrees

configuration value, 22ablog_main() (in module ablog.commands), 11ablog_serve() (in module ablog.commands), 11ablog_start() (in module ablog.start), 15ablog_website

configuration value, 22add() (ablog.blog.Collection method), 9ask_user() (in module ablog.start), 15

BBlog (class in ablog.blog), 8blog_archive_titles

configuration value, 19blog_authors

configuration value, 19blog_baseurl

configuration value, 19blog_default_author

configuration value, 19blog_default_language

configuration value, 20blog_default_location

configuration value, 20blog_feed_archives

configuration value, 20blog_feed_fulltext

configuration value, 20blog_feed_length

configuration value, 20blog_feed_subtitle

configuration value, 20blog_feed_titles

configuration value, 20blog_languages

configuration value, 19blog_locations

configuration value, 19blog_path

configuration value, 19blog_title

configuration value, 19

Ccatalog (ablog.blog.Collection attribute), 9Collection (class in ablog.blog), 9configuration value

ablog_builder, 22ablog_doctrees, 22ablog_website, 22blog_archive_titles, 19blog_authors, 19blog_baseurl, 19blog_default_author, 19blog_default_language, 20blog_default_location, 20blog_feed_archives, 20blog_feed_fulltext, 20blog_feed_length, 20blog_feed_subtitle, 20blog_feed_titles, 20blog_languages, 19blog_locations, 19blog_path, 19blog_title, 19disqus_drafts, 21disqus_pages, 21disqus_shortname, 21fontawesome_css_file, 21fontawesome_included, 21fontawesome_link_cdn, 21github_pages, 22post_always_section, 20

47

ABlog, Release 0.10.2.dev6

post_auto_excerpt, 20post_auto_image, 20post_date_format, 20post_redirect_refresh, 20

Ddisqus_drafts

configuration value, 21disqus_pages

configuration value, 21disqus_shortname

configuration value, 21docname (ablog.blog.Collection attribute), 9

Ffeed_path (ablog.blog.Blog attribute), 8final_argument_whitespace

(ablog.post.PostDirective attribute), 12final_argument_whitespace

(ablog.post.PostListDirective attribute), 13fontawesome_css_file

configuration value, 21fontawesome_included

configuration value, 21fontawesome_link_cdn

configuration value, 21

Ggenerate() (in module ablog.start), 15generate_archive_pages() (in module

ablog.post), 14generate_atom_feeds() (in module ablog.post),

14github_pages

configuration value, 22

Hhas_content (ablog.post.PostDirective attribute), 12has_content (ablog.post.PostListDirective attribute),

13

Nnext (ablog.blog.Post attribute), 10

Ooption_spec (ablog.post.PostDirective attribute), 12option_spec (ablog.post.PostListDirective attribute),

13optional_arguments (ablog.post.PostDirective at-

tribute), 12optional_arguments (ablog.post.PostListDirective

attribute), 13

Ppage_id() (ablog.blog.Blog method), 8page_url() (ablog.blog.Blog method), 8path (ablog.blog.Collection attribute), 9Post (class in ablog.blog), 9post (directive), 34post_always_section

configuration value, 20post_auto_excerpt

configuration value, 20post_auto_image

configuration value, 20post_date_format

configuration value, 20post_redirect_refresh

configuration value, 20PostDirective (class in ablog.post), 11PostList (class in ablog.post), 12postlist (directive), 36PostListDirective (class in ablog.post), 12PostNode (class in ablog.post), 13prev (ablog.blog.Post attribute), 10process_postlist() (in module ablog.post), 14process_posts() (in module ablog.post), 14purge_posts() (in module ablog.post), 15

Rrecent() (ablog.blog.Blog method), 8register() (ablog.blog.Blog method), 8register_posts() (in module ablog.post), 15relsize() (ablog.blog.Collection method), 9required_arguments (ablog.post.PostDirective at-

tribute), 12required_arguments (ablog.post.PostListDirective

attribute), 13required_arguments (ablog.post.UpdateDirective

attribute), 14run() (ablog.post.PostDirective method), 12run() (ablog.post.PostListDirective method), 13run() (ablog.post.UpdateDirective method), 14

Ssetup() (in module ablog), 15

Tto_html() (ablog.blog.Post method), 10

Uupdate (directive), 35UpdateDirective (class in ablog.post), 13UpdateNode (class in ablog.post), 14

48 Index