Adding upstream version 0.11.12.upstream/0.11.12upstream

Signed-off-by: Daniel Baumann <daniel@debian.org>

1 files changed, 291 insertions, 0 deletions

diff --git a/docs/manual/ablog-configuration-options.rst b/docs/manual/ablog-configuration-options.rst
new file mode 100644
index 0000000..9b25fb3
--- /dev/null
+++ b/docs/manual/ablog-configuration-options.rst
@@ -0,0 +1,291 @@
+.. _config:
+
+ABlog Configuration Options
+===========================
+
+.. post:: May 10, 2014
+   :tags: config
+   :author: Ahmet
+   :category: Manual
+   :location: Pittsburgh
+
+
+This post describes ABlog configuration options that go in :ref:`Sphinx build configuration file <sphinx:build-config>`.
+
+General options
+---------------
+
+.. confval:: blog_path
+
+   A path relative to the configuration directory for blog archive pages.
+   Default is ``'blog'``.
+
+Authors, languages, & locations
+-------------------------------
+
+.. confval:: blog_authors
+
+   A dictionary of author names mapping to author full display names and links.
+   Dictionary keys are what should be 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'),
+     }
+
+.. confval:: blog_default_author
+
+   Name of the default author defined in :confval:`blog_authors`.
+   Default is ``None``.
+
+.. confval:: blog_languages
+
+   A dictionary of language code names mapping to full display names and links of these languages.
+   Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations.
+   Default is ``{}``.
+   Example::
+
+     blog_languages = {
+         'en': ('English', None),
+     }
+
+.. confval:: blog_default_language
+
+   Code name of the default language defined in :confval:`blog_languages`.
+   Default is ``None``.
+
+.. confval:: blog_locations
+
+   A dictionary of location names mapping to full display names and links of these locations.
+   Similar to :confval:`blog_authors`, dictionary keys should be used in ``post`` directive to refer to the locations.
+   Default is ``{}``.
+
+.. confval:: blog_default_location
+
+   Name of the default location defined in :confval:`blog_locations`.
+   Default is ``None``.
+
+.. update:: Sep 15, 2014
+
+   Added :confval:`blog_languages` and :confval:`blog_default_language` configuration variables.
+
+Post related
+------------
+
+.. confval:: post_date_format
+
+   Date display format (default is ``'%b %d, %Y'``, e.g., ``12 August 2024``) for published posts that goes as input to :meth:`datetime.date.strftime`.
+
+.. confval:: post_date_format_short
+
+   Date display format in recent posts sidebar (default is ``'%d %B'``, e.g., ``12 October``) for published posts that goes as input to :meth:`datetime.date.strftime`.
+
+.. confval:: post_auto_excerpt
+
+   Number of paragraphs (default is ``1``) that will be displayed as an excerpt from the post.
+   Setting this ``0`` will result in displaying no post excerpt in archive pages.
+   This option can be set on a per post basis using :rst:dir:`post` directive option ``excerpt``.
+
+   See :ref:`post-excerpts-and-images` for a more detailed discussion.
+
+.. confval:: post_auto_image
+
+   Index of the image that will be displayed in the excerpt of the post.
+   Default is ``0``, meaning no image.
+   Setting this to ``1`` will include the first image, when available, to the excerpt.
+   This option can be set on a per post basis using :rst:dir:`post` directive option ``image``.
+
+.. confval:: post_redirect_refresh
+
+   Number of seconds (default is ``5``) that a redirect page waits before refreshing the page to redirect to the post.
+
+.. confval:: post_always_section
+
+   When ``True``, post title and excerpt is always taken from the section that contains the :rst:dir:`post` directive, instead of the document.
+   This is the behavior when :rst:dir:`post` is used multiple times in a document.
+   Default is ``False``.
+
+.. confval:: post_show_prev_next
+
+    When ``True``, links to the previous and next posts will be rendered at the bottom of the page.
+    Default is ``True``
+
+Blog feeds
+----------
+
+Turn feeds on by setting :confval:`blog_baseurl` configuration variable.
+
+.. confval:: blog_baseurl
+
+   Base URL for the website, turns on generating feeds. E.g., ``https://ablog.readthedocs.io``.
+
+Then optionally set the following:
+
+.. confval:: blog_title
+
+   The “title” for the blog, used in feeds title (not archive web pages title).  Default is ``'Blog'``.
+
+.. confval:: blog_archive_titles
+
+   Choose to archive only post titles in collection pages, default is ``False``.
+
+.. confval:: blog_feed_archives
+
+   Choose to create feeds per author, location, tag, category, and year, default is ``False``.
+
+.. confval:: blog_feed_fulltext
+
+   Choose to display full text in blog feeds, default is ``False``.
+
+.. confval:: blog_feed_subtitle
+
+   Blog feed subtitle, default is ``None``.
+
+.. confval:: blog_feed_titles
+
+   Choose to feed only post titles, default is ``False``.
+
+.. confval:: blog_feed_templates
+
+   A dictionary of feed filename roots mapping to nested dictionaries of feed entry
+   elements, ``title``, ``summary``, and/or ``content``, and a `Jinja2`_ template which will be
+   used to render the value used for that element in that feed.  Templates are rendered
+   with the the following context:
+   - ``feed_length``
+   - ``feed_fulltext``
+   - ``feed_posts``
+   - ``pagename``
+   - ``feed_title``
+   - ``feed_url``
+   - ``feed``
+   - ``post``
+   - ``post_url``
+   - ``content``
+   - ``feed_entry``
+   - ``title``
+   - ``summary``
+   - ``blog``
+   - ``url``
+   - ``app``
+   Default is: ``{"atom": {}}``
+   Example to add an additional feed for posting to social media::
+
+      blog_feed_templates = {
+            # Use defaults, no templates
+            "atom": {},
+            # Create content text suitable posting to social media
+            "social": {
+               # Format tags as hashtags and append to the content
+               "content": "{{ title }}{% for tag in post.tags %}"
+               " #{{ tag.name|trim()|replace(' ', '') }}"
+               "{% endfor %}",
+            },
+      }
+
+.. confval:: blog_feed_length
+
+   Specify number of recent posts to include in feeds, default is ``None`` for all posts.
+
+.. update:: Aug 24, 2014
+
+   Added :confval:`blog_feed_archives`, :confval:`blog_feed_fulltext`, :confval:`blog_feed_subtitle`, and :confval:`post_always_section` options.
+
+.. update:: Nov 27, 2014
+
+   Added :confval:`blog_feed_titles`, :confval:`blog_feed_length`, and :confval:`blog_archive_titles` options.
+
+.. update:: Mar 20, 2021
+
+   Added :confval:`blog_feed_templates` option.
+
+.. _fa:
+.. _Jinja2: https://jinja.palletsprojects.com/
+
+.. _font-awesome:
+
+Font awesome
+------------
+
+ABlog templates will use of `Font Awesome`_ icons if one of the following is set:
+
+.. _Font Awesome: https://fontawesome.com/
+
+.. confval:: fontawesome_link_cdn
+
+   URL to `Font Awesome`_ :file:`.css` hosted at `Bootstrap CDN`_ or anywhere else.
+   Default: ``None``
+
+   .. _Bootstrap CDN: https://www.bootstrapcdn.com/fontawesome/
+
+.. update:: Jul 29, 2015
+
+   :confval:`fontawesome_link_cdn` was a *boolean* option, and now became a *string* to enable using desired version of `Font Awesome`_.
+   To get the old behavior, use ``‘https://netdna.bootstrapcdn.com/font-awesome/4.0.3/css/font-awesome.min.css'``.
+
+.. confval:: fontawesome_included
+
+   Sphinx_ theme already links to `Font Awesome`_.
+   Default: ``False``
+
+Alternatively, you can provide the path to `Font Awesome`_ :file:`.css` with the following configuration option:
+
+.. confval:: fontawesome_css_file
+
+   Path to `Font Awesome`_ :file:`.css` (default is ``None``) that will be linked to in HTML output by ABlog.
+
+.. _disqus-integration:
+
+Disqus integration
+------------------
+
+Of course one cannot think of a blog that doesn't allow for visitors to comment.
+You can enable Disqus_ by setting :confval:`disqus_shortname` and :confval:`blog_baseurl` variables.
+The reason for requiring :confval:`blog_baseurl` to be specified as of v0.7.2 is to ensure that Disqus associates correct URLs with threads when you serve new posts locally for the first time.
+
+.. confval:: disqus_shortname
+
+   Disqus_ short name for the website.
+
+.. confval:: disqus_pages
+
+   Choose to disqus pages that are not posts, default is ``False``.
+
+.. confval:: disqus_drafts
+
+   Choose to disqus posts that are drafts (without a published date), default is ``False``.
+
+Isso integration
+----------------
+
+An alternative to Disqus, is `Isso <https://isso-comments.de/>`__.
+Integration is provided by `sphinxnotes-isso`_ and the instructions there.
+
+.. _sphinxnotes-isso: https://sphinx-notes.github.io/isso/
+
+Command Options
+---------------
+
+.. update:: Apr 7, 2015
+
+   Added :ref:`commands` options.
+
+.. confval:: ablog_website
+
+   Directory name for build output files. Default is ``_website``.
+
+.. confval:: ablog_doctrees
+
+   Directory name for build cache files. Default is ``.doctrees``.
+
+.. confval:: ablog_builder
+
+   HTML builder, default is ``dirhtml``. Build HTML pages, but with a single directory per document.
+   Makes for prettier URLs (no .html) if served from a webserver. Alternative is ``html`` to build one HTML file per document.
+
+.. confval:: github_pages
+
+   GitHub user name used by ``ablog deploy`` command.
+   See :ref:`deploy` and :ref:`deploy-to-github-pages` for more information.