Expand documentation on is_serial

tobinus · Jan 29, 2020 · 72d3cc9 · 72d3cc9
1 parent 28db7d8
commit 72d3cc9
Show file tree

Hide file tree

Showing 4 changed files with 39 additions and 5 deletions.
diff --git a/doc/conf.py b/doc/conf.py
@@ -57,7 +57,7 @@ def iad_add_directive_header(self, sig):
 
 # General information about the project.
 project = u'PodGen'
-copyright = u'2014, Lars Kiesow. Modified work © 2019, Thorben Dahl'
+copyright = u'2014, Lars Kiesow. Modified work © 2020, Thorben Dahl'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

diff --git a/doc/usage_guide/index.rst b/doc/usage_guide/index.rst
@@ -2,6 +2,8 @@
 Usage Guide
 ===========
 
+This part of the manual provides a guided tour of the PodGen library.
+
 .. toctree::
    :maxdepth: 1
 

diff --git a/doc/usage_guide/podcasts.rst b/doc/usage_guide/podcasts.rst
@@ -48,6 +48,38 @@ A podcast's image is worth special attention::
 
 Even though the image *technically* is optional, you won't reach people without it.
 
+
+The two types of podcasts
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+There are two types of podcasts in the world (according to Apple Podcasts, anyway):
+
+* **Episodic** podcasts are podcasts whose episodes are meant to be consumed in any order.
+  New listeners will likely start with the newest episode.
+  This is the traditional type of podcast, with examples like "The Daily" and "The Joe Rogan Experience".
+  Each episode of an episodic podcast is largely self-contained, although there may be
+  recurring jokes and references to older episodes.
+
+* **Serial** podcasts are podcasts whose episodes must be consumed from beginning to end.
+  New listeners will likely start with the first episode of the current season.
+  This is a newer phenomenon, made popular by the appropriately titled podcast "Serial".
+  Each episode of a serial podcast starts off where the last episode ended, though the seasons
+  are independent from one another.
+
+If you don't do anything, PodGen will assume that your podcast is episodic.
+
+If your podcast is serial, you can set the :attr:`~podgen.Podcast.is_serial` attribute to :data:`True`, like this::
+
+   p.is_serial = True
+
+.. note::
+
+   When :attr:`~podgen.Podcast.is_serial` is set to :data:`True`,
+   all episodes must be given an episode number.
+   Additionally, it is recommended that you associate each episode with a season.
+   This is covered on the next page.
+
+
 Optional attributes
 ~~~~~~~~~~~~~~~~~~~
 

diff --git a/podgen/podcast.py b/podgen/podcast.py
@@ -328,15 +328,15 @@ def __init__(self, **kwargs):
         season. This is used for podcasts like "Serial", where the second
         episode continues where the first episode left off.
         
-        Set this to ``True`` to mark the podcast as serial.
-        Keep the default value, ``False``, to mark the podcast as
+        Set this to :data:`True` to mark the podcast as serial.
+        Keep the default value, :data:`False`, to mark the podcast as
         episodic.
 
         .. note::
 
            To preserve backwards compatibility, no RSS element will be
-           produced when this is set to ``False``. This will be interpreted as
-           "episodic" by podcast applications.
+           produced when this is set to :data:`False`. This will be interpreted
+           as "episodic" by podcast applications.
 
         :type: :obj:`bool`
         :RSS: itunes:type