update docs

Signed-off-by: Chris Warrick <kwpolska@gmail.com>
getnikola · Jan 13, 2015 · de3727e · de3727e
1 parent 21bfb8f
commit de3727e
Show file tree

Hide file tree

Showing 11 changed files with 419 additions and 153 deletions.
diff --git a/listings/conf.py b/listings/conf.py
diff --git a/stories/CHANGES.txt b/stories/CHANGES.txt
@@ -1,3 +1,90 @@
+New in v7.3.0
+=============
+
+Features
+--------
+
+* Added ``-a``, ``--author`` option to set post author field
+* Added option INDEXES_PRETTY_PAGE_URL to make URLs for indexes
+  pages more pretty. (Issue #1548)
+* Added ``-i``, ``--import`` argument to ``new_post`` for importing
+  existing post contents (Issue #1385)
+* Added warning about ``password`` in posts being insecure
+  (Issue #1547)
+* INDEXES_TITLE and INDEXES_PAGES are translatable (Issue #1544)
+* Added new option ARCHIVES_ARE_INDEXES which allows archive pages
+  which list posts to be rendered with the post contents.
+  (Issue #1537)
+* Added new option INDEXES_STATIC which allows to define the
+  page ordering for indexes (Issue #1537). Also, if tag pages are
+  created as indexes, they will behave more close to the
+  default indexes.
+* Use ``table`` line-numbering style with reST code, making
+  copy-pasting code possible (Issue #1285)
+* Tag and category pages are now more separated. The prefix for
+  category pages can be changed and the folder can be modified
+  independently of the tags' folder. (Issue #1535)
+* Writing the tag cloud data file can now be disabled. Will be
+  disabled by default in the future. (Issue #1535)
+* The ``utils.config_changed`` function now takes an optional extra
+  argument, ``identifier``, used to identify the source of a specific
+  dependency save.  As such, ALL your files will be rebuilt after
+  upgrading. (Issue #1526 via #1521)
+* New option GALLERY_FOLDERS replacing GALLERY_PATH (Issue #1511)
+* New PANDOC_OPTIONS option (Issue #1492)
+* New tab-width option in code-block directive (Issue #1514)
+* New option TAG_PAGES_DESCRIPTIONS for optionally making individual
+  tag pages more unique and interesting (Issue #1486)
+* New option LISTINGS_FOLDERS (which replaces LISTINGS_FOLDER) which
+  allows to separate input and output folder names for listings, and
+  allows to have more than one listings folder (Issue #1499)
+* ReST listing directive now honors alternative listings folder names
+  (Issue #1499)
+* New command line option --conf= to specify the configuration file
+  (default is conf.py) (Issue #1501)
+* Added Arabic translation (by darkwise)
+* Added Danish translation (by mikkelkristiansen)
+* Added Indonesian translation (by Willy Sudiarto Raharjo)
+* Added Korean translation (by Dong Geun)
+* Added Serbian translation (by Ivan Radeljic)
+* Added Swedish translation (by Johan Sommerfeld)
+* New advanced option RSS_LINKS_APPEND_QUERY for tracking traffic
+  from RSS subscribers
+* Add ``robots`` meta tag with value ``noindex`` for drafts
+  (Issue #1489)
+* New option TAGLIST_MINIMUM_POSTS allows hiding unpopular tags from
+  the tag index page (Issue #1484)
+* New options CREATE_FULL_ARCHIVES and CREATE_DAILY_ARCHIVE which
+  allow to create non-hierarchical archives and archives for days,
+  respectively (Issue #1494)
+* New plugin for creating image thumbnails, and a corresponding reST
+  plugin (Issue #1527)
+
+Bugfixes
+--------
+
+* Handle over-and-under-lined titles in rst for guessing title (Issue #1539)
+* Don't apply colorbox to figures if they are of islink class. (Issue #1536)
+* Turned minify_lines into a no-op (Issue #1497)
+* Don’t classify unpublished posts as pages (Issue #1577)
+* Fixed a ``TranslatableSetting.langformat`` race condition
+* Fixed ``TranslatableSetting`` instantiation in
+  ``TranslatableSetting.langformat`` (Issue #1571)
+* Fixed ``rss.xsl`` path for blogs not deployed to server root
+  (Issue #1563)
+* Respect SHOW_UNTRANSLATED_POSTS = False in archives
+  and for untranslated source files (Issue #1360)
+* Make sure drafts don’t appear in sitemaps with multiple languages
+  (Issue #1489)
+* Make site.posts_per_file cover all languages (Issues #1270, #1489)
+* Fix ANNOTATIONS not working at all (Issue #1477)
+* Fix asking questions with Unicode chars in Python 2 (Issue #1476)
+* Use ADDITIONAL_METADATA with the two-file format (Issue #1471)
+* Make previewimage compatible with sites deployed to subdirectories
+  (Issue #1473)
+* Make sitemaps work on sites deployed to subdirectories
+  (Issue #1472)
+
 New in v7.2.0
 =============
 
@@ -655,7 +742,7 @@ Bugfixes
 * Added .rst to the default reStructuredText extensions (via Issue #542)
 * Moved the sample site to the new one-file format (Issue #542)
 * Escape HTML in titles (Issue #537)
-* Fixed issues with index pages indices (Issue #532)
+* Fixed issues with index pages indexes (Issue #532)
 * Fixed IPython plugin to work with the latest IPython.nbconvert machinery
 * Fixed failing build because of hidden folders and files inside post folder
 

diff --git a/stories/conf.txt b/stories/conf.txt
@@ -1,9 +1,9 @@
-.. title: Nikola v7.2.0 configuration file
+.. title: Nikola v7.3.0 configuration file
 .. slug: conf
 .. date: 2014-11-08 18:51:30 UTC
 .. description: The Nikola configuration file.
 .. type: text
 
-The default config file for Nikola v7.2.0 is reproduced below.
+The default config file for Nikola v7.3.0 is reproduced below.
 
 .. listing:: conf.py python
diff --git a/stories/creating-a-site.txt b/stories/creating-a-site.txt
@@ -1,5 +1,5 @@
 .. slug: creating-a-site-not-a-blog-with-nikola
-.. date: 2013/03/01 12:49:41
+.. date: 2015-01-10 10:00:00 UTC
 .. tags: nikola, python
 .. link:
 .. description:
@@ -10,19 +10,22 @@ Creating a Site (Not a Blog) with Nikola
 
 .. class:: lead
 
-One of the most frequent questions I get about Nikola is "but how do
-I create a site that's not a blog?". And of course, that's because the
-documentation is heavily blog-oriented. This document will change that ;-)
+One of the most frequent questions I get about Nikola is “but how do
+I create a site that’s not a blog?”. And of course, that’s because the
+documentation is heavily blog–oriented. This document will change that ;-)
 
 Since it started, Nikola has had the capabilities to create generic sites. For example,
-Nikola's `own site <http://getnikola.com>`_ is a fairly generic one. Let's go
+Nikola’s `own site <https://getnikola.com/>`_ is a fairly generic one. Let’s go
 step by step on how you can do something like that.
 
 As usual when starting a nikola site, you start with ``nikola init`` which creates a
-empty semi-configured site::
+empty (mostly) configured site::
 
     $ nikola init mysite
-    Created empty site at mysite.
+    Creating Nikola Site
+    ====================
+    ⋮
+    [1970-01-01T00:00:00Z] INFO: init: Created empty site at mysite.
 
 Then we go into the new ``mysite`` folder, and make the needed changes in the ``conf.py``
 configuration file:
@@ -40,8 +43,8 @@ configuration file:
     BLOG_TITLE = "Not a Blog"
     # This is the main URL for your site. It will be used
     # in a prominent link
-    SITE_URL = "http://notablog.ralsina.com.ar/"
-    BLOG_EMAIL = "ralsina@kde.org"
+    SITE_URL = "http://getnikola.com/"
+    BLOG_EMAIL = "ralsina@example.com"
     BLOG_DESCRIPTION = "This is a demo site (not a blog) for Nikola."
 
     #
@@ -58,12 +61,13 @@ configuration file:
 
 And now we are ready to create our first page::
 
-    $ nikola new_post -p
-    Creating New Post
+    $ nikola new_page
+    Creating New Page
     -----------------
 
-    Enter title: index
-    Your post's text is at:  pages/index.txt
+    Title: index
+    Scanning posts....done!
+    [1970-01-01T00:00:00Z] INFO: new_page: Your page's text is at: stories/index.rst
 
 .. note:: The ``-p`` option in the ``nikola new_post`` command means we are creating a page and not a blog post.
 
@@ -74,32 +78,30 @@ We can now build and preview our site::
     .  render_site:output/categories/index.html
     .  render_sources:output/index.txt
     .  render_rss:output/rss.xml
-    :
-    :
-    : [Much more of the same]
-
+    ⋮
     $ nikola serve
-    Serving HTTP on 127.0.0.1 port 8000 ...
+    [1970-01-01T00:00:00Z] INFO: serve: Serving HTTP on 0.0.0.0 port 8000...
+
 
-And you can see your (very empty) site in http://localhost:8000
+And you can see your (very empty) site in http://localhost:8000/
 
-So, what's in that ``pages/index.txt`` file?
+So, what’s in that ``pages/index.txt`` file?
 
 .. code-block:: rest
 
     .. title: index
     .. slug: index
-    .. date: 2013/03/01 10:26:17
+    .. date: 1970-01-01 00:00:00 UTC
     .. tags:
     .. link:
     .. description:
 
 
     Write your post here.
 
-Title is the page title, slug is the name of the generated HTML file
-(in this case it would be ``index.html``) the date doesn't matter much in
-not-blogs, same for tags and link. Description is useful for SEO purposes
+``title`` is the page title, ``slug`` is the name of the generated HTML file
+(in this case it would be ``index.html``). ``date``, ``tags`` and ``link``
+doesn’t matter at all in stories. ``description`` is useful for SEO purposes
 if you care for that.
 
 And below, the content. By default you are expected to use
@@ -108,32 +110,31 @@ Nikola supports a ton of formats, including Markdown, plain HTML, BBCode,
 Wiki, and Textile.
 
 So, let's give the page a nicer title, and some fake content. Since the default
-Nikola theme (called "bootstrap") is based on `bootstrap 2 <http://getbootstrap.com/2.3.2/>`_
+Nikola theme (called ``bootstrap3``) is based on `Bootstrap <http://getbootstrap.com/>`_
 you can use anything you like from it:
 
 .. code-block:: rest
 
     .. title: Welcome To The Fake Site
     .. slug: index
-    .. date: 2013/03/01 10:26:17
+    .. date: 1970-01-01 00:00:00 UTC
     .. tags:
     .. link:
     .. description: Fake Site version 1, welcome page!
 
 
-    .. class:: hero-unit span6
+    .. class:: jumbotron col-md-6
 
     .. admonition:: This is a Fake Site
 
         It pretends to be about things, but is really just an example.
-        So, don't click this button, it leads nowhere.
 
-        .. class:: btn
+        .. raw:: html
 
-        Click Me!
+           <a href="https://getnikola.com/" class="btn btn-primary btn-lg">Click Me!</a>
 
 
-    .. class:: span5
+    .. class:: col-md-5
 
     Lorem ipsum dolor sit amet, consectetur adipiscing elit. Mauris non nunc turpis.
     Phasellus a ullamcorper leo. Sed fringilla dapibus orci eu ornare. Quisque
@@ -146,15 +147,13 @@ you can use anything you like from it:
     aptent taciti sociosqu ad litora torquent per conubia nostra, per inceptos
     himenaeos.
 
-    [And more in the same vein]
-
 .. admonition:: TIP: Nice URLs
 
-   If you like your URLs without the ".html" then you want to create folders and
+   If you like your URLs without the ``.html`` then you want to create folders and
    put the pages in ``index.html`` inside them using the ``PRETTY_URLS`` option.
 
 And that's it. You will want to change the NAVIGATION_LINKS option to create a reasonable
-"menu" for your site, you will want to hack the theme (check ``nikola help bootswatch_theme``
+menu for your site, you will want to modify the theme (check ``nikola help bootswatch_theme``
 for a quick & dirty solution), and you may want to add a blog later on, for company news
 or whatever.
 
@@ -167,9 +166,10 @@ or whatever.
         POSTS = [("posts/*.txt", "blog", "post.tmpl", True)]
 
     Create a post with ``nikola new_post`` and that's it, you now have a blog
-    in http://yoursite.com/blog (you may want to add links to it in NAVIGATION_LINKS of course).
+    in the ``/blog/`` subdirectory of your site — you may want to link to
+    it in ``NAVIGATION_LINKS``.
 
-You can see the finished site in http://notablog.ralsina.com.ar and its full configuration in
-http://ralsina.me/listings/notablog/conf.py.html
+If you want to see a site implementing all of the above, check out `the Nikola
+website <https://getnikola.com/>`_.
 
 I hope this was helpful!
diff --git a/stories/creating-a-theme.txt b/stories/creating-a-theme.txt
@@ -17,6 +17,10 @@ so we get good support for slides and galleries.
 
 I will try to create a theme that looks like `Vinicius Massuchetto's Monospace Theme <http://wordpress.org/themes/monospace>`_.
 
+.. danger::
+
+   This document is outdated!  Recommendations in this post may not work!
+
 .. TEASER_END
 
 Starting The Theme

diff --git a/stories/extending.txt b/stories/extending.txt
@@ -8,7 +8,7 @@
 Extending Nikola
 ================
 
-:Version: 7.2.0
+:Version: 7.3.0
 :Author: Roberto Alsina <ralsina@netmanagers.com.ar>
 
 .. class:: alert alert-info pull-right

diff --git a/stories/getting-help.txt b/stories/getting-help.txt
@@ -3,7 +3,7 @@
 .. date: 1970-01-01 15:00:00
 .. description: Get help using Nikola, or contact us.
 
-:Version: 7.2.0
+:Version: 7.3.0
 
 .. class:: alert alert-info pull-right