Minor documentation improvements

docs/settings.rst

@@ -4,7 +4,7 @@ Settings
 Pelican is configurable thanks to a settings file you can pass to
 the command line::
 
-    pelican content -s path/to/your/settingsfile.py
+    pelican content -s path/to/your/pelicanconf.py
 
 (If you used the ``pelican-quickstart`` command, your primary settings file will
 be named ``pelicanconf.py`` by default.)
@@ -28,6 +28,7 @@ templates, which allows you to use your settings to add site-wide content.
 
 Here is a list of settings for Pelican:
 
+
 Basic settings
 ==============
 
@@ -225,9 +226,9 @@ configuration files for local development and publishing, respectively.
 You can customize the URLs and locations where files will be saved. The
 ``*_URL`` and ``*_SAVE_AS`` variables use Python's format strings. These
 variables allow you to place your articles in a location such as
-``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs. These
+``{slug}/index.html`` and link to them as ``{slug}`` for clean URLs (see
-settings give you the flexibility to place your articles and pages anywhere you
+example below). These settings give you the flexibility to place your articles
-want.
+and pages anywhere you want.
 
 .. note::
     If you specify a ``datetime`` directive, it will be substituted using the
@@ -250,30 +251,12 @@ Example usage:
 
 * ``ARTICLE_URL = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/'``
 * ``ARTICLE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/{date:%d}/{slug}/index.html'``
+* ``PAGE_URL = 'pages/{slug}/'``
+* ``PAGE_SAVE_AS = 'pages/{slug}/index.html'``
 
-This would save your articles in something like ``/posts/2011/Aug/07/sample-post/index.html``,
+This would save your articles into something like ``/posts/2011/Aug/07/sample-post/index.html``,
-and the URL to this would be ``/posts/2011/Aug/07/sample-post/``.
+save your pages into ``/pages/about/index.html``, and render them available at
-
+URLs of ``/posts/2011/Aug/07/sample-post/`` and ``/pages/about/``, respectively.
-Pelican can optionally create per-year, per-month, and per-day archives of your
-posts. These secondary archives are disabled by default but are automatically
-enabled if you supply format strings for their respective ``_SAVE_AS`` settings.
-Period archives fit intuitively with the hierarchical model of web URLs and can
-make it easier for readers to navigate through the posts you've written over time.
-
-Example usage:
-
-* ``YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'``
-* ``MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'``
-
-With these settings, Pelican will create an archive of all your posts for the
-year at (for instance) ``posts/2011/index.html`` and an archive of all your
-posts for the month at ``posts/2011/Aug/index.html``.
-
-.. note::
-    Period archives work best when the final path segment is ``index.html``.
-    This way a reader can remove a portion of your URL and automatically
-    arrive at an appropriate archive of posts, without having to specify
-    a page name.
 
 ======================================================  ==============================================================
 Setting name (followed by default value, if any)        What does it do?
@@ -339,22 +322,48 @@ Setting name (followed by default value, if any)        What does it do?
     set the corresponding ``*_SAVE_AS`` setting to ``''`` to prevent the
     relevant page from being generated.
 
+Pelican can optionally create per-year, per-month, and per-day archives of your
+posts. These secondary archives are disabled by default but are automatically
+enabled if you supply format strings for their respective ``_SAVE_AS`` settings.
+Period archives fit intuitively with the hierarchical model of web URLs and can
+make it easier for readers to navigate through the posts you've written over time.
+
+Example usage:
+
+* ``YEAR_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/index.html'``
+* ``MONTH_ARCHIVE_SAVE_AS = 'posts/{date:%Y}/{date:%b}/index.html'``
+
+With these settings, Pelican will create an archive of all your posts for the
+year at (for instance) ``posts/2011/index.html`` and an archive of all your
+posts for the month at ``posts/2011/Aug/index.html``.
+
+.. note::
+    Period archives work best when the final path segment is ``index.html``.
+    This way a reader can remove a portion of your URL and automatically
+    arrive at an appropriate archive of posts, without having to specify
+    a page name.
+
 ``DIRECT_TEMPLATES``, which are ``('index', 'tags', 'categories', 'archives')``
 by default, work a bit differently than noted above. Only the ``_SAVE_AS``
 settings are available:
 
-=============================================  ===============================================
+=============================================  ======================================================
 Setting name (followed by default value)       What does it do?
-=============================================  ===============================================
+=============================================  ======================================================
 ``ARCHIVES_SAVE_AS = 'archives.html'``         The location to save the article archives page.
+``YEAR_ARCHIVE_SAVE_AS = ''``                  The location to save per-year archives of your posts.
+``MONTH_ARCHIVE_SAVE_AS = ''``                 The location to save per-month archives of your posts.
+``DAY_ARCHIVE_SAVE_AS = ''``                   The location to save per-day archives of your posts.
 ``AUTHORS_SAVE_AS = 'authors.html'``           The location to save the author list.
 ``CATEGORIES_SAVE_AS = 'categories.html'``     The location to save the category list.
 ``TAGS_SAVE_AS = 'tags.html'``                 The location to save the tag list.
-=============================================  ===============================================
+=============================================  ======================================================
 
-URLs for direct template pages are theme-dependent. Some themes hard-code them:
+URLs for direct template pages are theme-dependent. Some themes use
+corresponding ``*_URL`` setting as string, while others hard-code them:
 ``'archives.html'``, ``'authors.html'``, ``'categories.html'``, ``'tags.html'``.
 
+
 Timezone
 --------
 
@@ -428,6 +437,7 @@ can get a list of available locales via the ``locale -a`` command; see manpage
 
 .. _template_pages:
 
+
 Template pages
 ==============
 
@@ -445,6 +455,7 @@ your resume, and a contact page — you could have::
 
 .. _path_metadata:
 
+
 Path metadata
 =============
 
@@ -478,16 +489,17 @@ particular file:
     # STATIC_SAVE_AS = '{path}'
     # STATIC_URL = '{path}'
     STATIC_PATHS = [
-        'extra/robots.txt',
+        'static/robots.txt',
         ]
     EXTRA_PATH_METADATA = {
-        'extra/robots.txt': {'path': 'robots.txt'},
+        'static/robots.txt': {'path': 'robots.txt'},
         }
 
 __ internal_metadata__
 .. _group name notation:
    http://docs.python.org/3/library/re.html#regular-expression-syntax
 
+
 Feed settings
 =============
 
@@ -530,6 +542,7 @@ If you don't want to generate some or any of these feeds, set the above variable
 
 .. [2] %s is the name of the category.
 
+
 FeedBurner
 ----------
 
@@ -549,6 +562,7 @@ Address". In this example, the "Original Feed" would be
 ``http://www.example.com/thymefeeds/main.xml`` and the "Feed Address" suffix
 would be ``thymefeeds/main.xml``.
 
+
 Pagination
 ==========
 
@@ -572,6 +586,7 @@ Setting name (followed by default value, if any)    What does it do?
                                                     pagination output.
 ================================================    =====================================================
 
+
 Using Pagination Patterns
 -------------------------
 
@@ -594,6 +609,7 @@ This would cause the first page to be written to
 ``{base_name}/index.html``, and subsequent ones would be written into
 ``page/{number}`` directories.
 
+
 Tag cloud
 =========
 
@@ -640,6 +656,7 @@ For example::
 
     ...
 
+
 Translations
 ============
 
@@ -656,6 +673,7 @@ Setting name (followed by default value, if any)            What does it do?
 
 .. [3] %s is the language
 
+
 Ordering content
 ================
 
@@ -668,6 +686,7 @@ Setting name (followed by default value)            What does it do?
                                                     alphabetical order; default lists alphabetically.)
 ================================================    =====================================================
 
+
 Themes
 ======
 
@@ -752,6 +771,7 @@ adding the following to your configuration::
 
     CSS_FILE = "wide.css"
 
+
 Logging
 =======
 
@@ -769,6 +789,7 @@ For example: ``[(logging.WARN, 'TAG_SAVE_AS is set to False')]``
 
 .. _reading_only_modified_content:
 
+
 Reading only modified content
 =============================
 
@@ -835,6 +856,7 @@ from the ``--checksum`` option.
 
 .. _writing_only_selected_content:
 
+
 Writing only selected content
 =============================
 
@@ -848,6 +870,7 @@ on the command line using the ``--write-selected`` option, which
 accepts a comma-separated list of output file paths. By default this
 list is empty, so all output is written.
 
+
 Example settings
 ================
 

docs/themes.rst

@@ -16,6 +16,7 @@ then modified), you can specify that theme via the ``-t`` flag::
 If you'd rather not specify the theme on every invocation, you can define
 ``THEME`` in your settings to point to the location of your preferred theme.
 
+
 Structure
 =========
 
@@ -32,7 +33,7 @@ To make your own theme, you must follow the following structure::
         ├── authors.html          // must list all the authors
         ├── categories.html       // must list all the categories
         ├── category.html         // processed for each category
-        ├── index.html            // the index. List all the articles
+        ├── index.html            // the index (list all the articles)
         ├── page.html             // processed for each page
         ├── tag.html              // processed for each tag
         └── tags.html             // must list all the tags. Can be a tag cloud.
@@ -45,6 +46,7 @@ To make your own theme, you must follow the following structure::
   The template files listed above are mandatory; you can add your own templates
   if it helps you keep things organized while creating your theme.
 
+
 Templates and variables
 =======================
 
@@ -55,6 +57,7 @@ variables will be passed to each template at generation time.
 All templates will receive the variables defined in your settings file, as long
 as they are in all-caps. You can access them directly.
 
+
 Common variables
 ----------------
 
@@ -64,7 +67,7 @@ All of these settings will be available to all templates.
 Variable        Description
 =============   ===================================================
 output_file     The name of the file currently being generated. For
-                instance, when Pelican is rendering the homepage,
+                instance, when Pelican is rendering the home page,
                 output_file will be "index.html".
 articles        The list of articles, ordered descending by date.
                 All the elements are `Article` objects, so you can
@@ -81,6 +84,7 @@ categories      A list of (category, articles) tuples, containing
 pages           The list of pages
 =============   ===================================================
 
+
 Sorting
 -------
 
@@ -112,12 +116,13 @@ to the locale given in your settings::
 .. _datetime: http://docs.python.org/2/library/datetime.html#datetime-objects
 .. _strftime: http://docs.python.org/2/library/datetime.html#strftime-strptime-behavior
 
+
 index.html
 ----------
 
-This is the home page of your blog, generated at output/index.html.
+This is the home page or index of your blog, generated at ``index.html``.
 
-If pagination is active, subsequent pages will reside in output/index`n`.html.
+If pagination is active, subsequent pages will reside in ``index{number}.html``.
 
 ======================  ===================================================
 Variable                Description
@@ -139,14 +144,14 @@ dates_next_page         The next page of articles, ordered by date,
 page_name               'index' -- useful for pagination links
 ======================  ===================================================
 
+
 author.html
 -------------
 
 This template will be processed for each of the existing authors, with
-output generated at output/author/`author_name`.html.
+output generated according to the ``AUTHOR_SAVE_AS`` setting (`Default:`
-
+``author/{author_name}.html``). If pagination is active, subsequent pages will by
-If pagination is active, subsequent pages will reside as defined by setting
+default reside at ``author/{author_name}{number}.html``.
-AUTHOR_SAVE_AS (`Default:` output/author/`author_name'n'`.html).
 
 ======================  ===================================================
 Variable                Description
@@ -173,14 +178,14 @@ page_name               AUTHOR_URL where everything after `{slug}` is
                         removed -- useful for pagination links
 ======================  ===================================================
 
+
 category.html
 -------------
 
 This template will be processed for each of the existing categories, with
-output generated at output/category/`category_name`.html.
+output generated according to the ``CATEGORY_SAVE_AS`` setting (`Default:`
-
+``category/{category_name}.html``). If pagination is active, subsequent pages will by
-If pagination is active, subsequent pages will reside as defined by setting
+default reside at ``category/{category_name}{number}.html``.
-CATEGORY_SAVE_AS (`Default:` output/category/`category_name'n'`.html).
 
 ======================  ===================================================
 Variable                Description
@@ -207,11 +212,14 @@ page_name               CATEGORY_URL where everything after `{slug}` is
                         removed -- useful for pagination links
 ======================  ===================================================
 
+
 article.html
 -------------
 
-This template will be processed for each article, with .html files saved
+This template will be processed for each article, with
-as output/`article_name`.html. Here are the specific variables it gets.
+output generated according to the ``ARTICLE_SAVE_AS`` setting (`Default:`
+``{article_name}.html``). The following variables are available when
+rendering.
 
 =============   ===================================================
 Variable        Description
@@ -249,8 +257,10 @@ image for the Facebook open graph tags that will change for each article:
 page.html
 ---------
 
-This template will be processed for each page, with corresponding .html files
+This template will be processed for each page, with
-saved as output/`page_name`.html.
+output generated according to the ``PAGE_SAVE_AS`` setting (`Default:`
+``pages/{page_name}.html``). The following variables are available when
+rendering.
 
 =============   ===================================================
 Variable        Description
@@ -259,14 +269,14 @@ page            The page object to be displayed. You can access its
                 title, slug, and content.
 =============   ===================================================
 
+
 tag.html
 --------
 
-This template will be processed for each tag, with corresponding .html files
+This template will be processed for each tag, with
-saved as output/tag/`tag_name`.html.
+output generated according to the ``TAG_SAVE_AS`` setting (`Default:`
-
+``tag/{tag_name}.html``). If pagination is active, subsequent pages will by
-If pagination is active, subsequent pages will reside as defined in setting
+default reside at ``tag/{tag_name}{number}.html``.
-TAG_SAVE_AS (`Default:` output/tag/`tag_name'n'`.html).
 
 ======================  ===================================================
 Variable                Description
@@ -293,12 +303,13 @@ page_name               TAG_URL where everything after `{slug}` is removed
                         -- useful for pagination links
 ======================  ===================================================
 
+
 period_archives.html
 --------------------
 
 This template will be processed for each year of your posts if a path
-for YEAR_ARCHIVE_SAVE_AS is defined, each month if MONTH_ARCHIVE_SAVE_AS
+for ``YEAR_ARCHIVE_SAVE_AS`` is defined, each month if ``MONTH_ARCHIVE_SAVE_AS``
-is defined and each day if DAY_ARCHIVE_SAVE_AS is defined.
+is defined, and each day if ``DAY_ARCHIVE_SAVE_AS`` is defined.
 
 ===================     ===================================================
 Variable                Description
@@ -313,8 +324,9 @@ period                  A tuple of the form (`year`, `month`, `day`) that
 
 ===================     ===================================================
 
-You can see an example of how to use `period` in the ``simple`` theme's
+You can see an example of how to use `period` in the `"simple" theme
-period_archives.html
+<https://github.com/getpelican/pelican/blob/master/pelican/themes/simple/templates/period_archives.html>`_.
+
 
 Feeds
 =====
@@ -346,7 +358,7 @@ missing, it will be replaced by the matching template from the ``simple`` theme.
 So if the HTML structure of a template in the ``simple`` theme is right for you,
 you don't have to write a new template from scratch.
 
-You can also extend templates from the ``simple`` themes in your own themes by
+You can also extend templates from the ``simple`` theme in your own themes by
 using the ``{% extends %}`` directive as in the following example:
 
 .. code-block:: html+jinja