**************************************************************** ``sphinxcontrib-newsfeed`` -- News Feed extension for Sphinx **************************************************************** Overview ======== ``sphinxcontrib-newsfeed`` is a extension for adding a simple *Blog*, *News* or *Announcements* section to a Sphinx_ website. Features: * Makes feed entries from Sphinx documents. * Generates a list of entries with teasers. * Saves the feed to a file in RSS format. * Supports comments via Disqus_. You can see this extension in action at http://htsql.org/blog/. For more examples, see ``demo`` directory in the source distribution. This software is written by Kirill Simonov (`Prometheus Research, LLC`_) and released under BSD license. Usage ===== To enable this extension, add the following line to ``conf.py``:: extensions.append('sphinxcontrib.newsfeed') To add a comment form to news entries, you also need to specify the Disqus_ website identifier:: disqus_shortname = '...' Now you can convert any Sphinx document to a news entry by using directive ``feed-entry``. For example:: Welcome!!! ========== .. feed-entry::📅 2012-01-01 Welcome to the news feed of **Elvensense**. Here we will post release announcements and other project news. Use ``cut`` directive to separate the entry teaser from the content:: Elvensense 96 is released ========================= .. feed-entry::📅 2012-12-31 We are proud to announce a new release of **Elvensense**. .. cut:: Specific changes since the last release: * An exciting feature was added. * An annoying bug was fixed. To make a list of news entries and generate an RSS file, use ``feed`` directive:: .. feed:: :rss: index.rss :title: Elvensense News release welcome The body of ``feed`` directive must list documents containing news entries (similar to ``toctree``). The options of ``feed`` directive define the name of the RSS file and describe the feed metadata. You need to manually update your HTML templates to add a link to the RSS feed:: <link rel="alternate" type="application/rss+xml" title="Elvensense News" href="/index.rss" /> Reference ========= Directives ---------- ``feed-entry`` Specifies an entry metadata. This directive has no body. Options: ``author`` The author of the post (optional). ``date`` The date of the post in ``YYYY-MM-DD`` format. ``feed`` Inserts a list of entries with teasers at the current location. This directive should contain a list of document names (similar to ``toctree``). This directive adds the documents to the hierarchy, so that you don't need to add the to ``toctree``. Options: ``rss`` Where to write the RSS feed (optional). ``title`` The name of the RSS channel. ``description`` Description of the RSS channel. ``link`` The website URL. ``cut`` Separates the entry teaser from the rest of the text. This directive has no options and no body. ``disqus`` Inserts a Disqus_ comment widget. Normally you don't need to use this directive for news entries since, if ``disqus_shortname`` parameter is set, Disqus comment form is encluded automatically with every feed entry. This directive allows you to use Disqus with regular Sphinx documents. Options: ``shortname`` The website identifier. Use to override ``disqus_shortname`` configuration parameter. ``identifier`` The page identifier. If not set, use the document name. ``title`` The title of the page. If not set, use the document title. Configuration parameters ------------------------ ``disqus_shortname`` Sets the unique identifier for a Disqus website. To acquire one, you need to register the website on http://disqus.com/. ``disqus_developer`` Sets the developer mode (``False`` or ``True``). CSS classes ----------- ``feed-meta`` Wraps for the post metadata block. ``feed-author`` Wraps the author name. ``feed-date`` Wraps the post date. ``feed-disqus`` Wraps the Disqus comment widget. ``feed-ref`` Wraps the post title in the list of posts. ``feed-more`` Wraps the *Read more...* link. .. _Sphinx: http://sphinx-doc.org/ .. _Disqus: http://disqus.org/ .. _Prometheus Research, LLC: http://prometheusresearch.com/ .. vim: set spell spelllang=en textwidth=72: