Various fixes and improvements to the docs

docs/changelog.rst

@@ -1,7 +1,7 @@
 Release history
 ###############
 
-3.0 (XXXX-XX-XX)
+3.0.0 (XXXX-XX-XX)
 ================
 
 * Refactored the way URLs are handled
@@ -11,15 +11,15 @@ Release history
 * Added a way to disable feed generation
 * Added support for ``DIRECT_TEMPLATES``
 * Allow multiple extensions for content files
-* Added less support
+* Added LESS support
 * Improved the import script
-* Fixed a bunch of bugs :-)
 * Added functional tests
 * Rsync support in the generated Makefile
 * Improved feed support (easily pluggable with Feedburner for instance)
 * Added support for ``abbr`` in reST
+* Fixed a bunch of bugs :-)
 
-2.8 (2012-02-28)
+2.8.0 (2012-02-28)
 ================
 
 * Dotclear importer

docs/contribute.rst

@@ -3,14 +3,17 @@ How to contribute?
 There are many ways to contribute to Pelican. You can enhance the
 documentation, add missing features, and fix bugs (or just report them).
 
-Don't hesitate to fork and make a pull request on GitHub.
+Don't hesitate to fork and make a pull request on GitHub. When doing so, please
+create a new feature branch as opposed to making your commits in the master
+branch.
 
 Setting up the development environment
 ======================================
 
 You're free to set up your development environment any way you like. Here is a
-way using virtualenv and virtualenvwrapper. If you don't have them, you can
+way using the `virtualenv <http://www.virtualenv.org/>`_ and `virtualenvwrapper
-install these packages via::
+<http://www.doughellmann.com/projects/virtualenvwrapper/>`_ tools. If you don't
+have them, you can install these both of these packages via::
 
     $ pip install virtualenvwrapper
 
@@ -22,26 +25,34 @@ To create a virtual environment, use the following syntax::
 
     $ mkvirtualenv pelican 
 
-To manually install the dependencies::
+To clone the Pelican source::
 
+    $ git clone https://github.com/getpelican/pelican.git src/pelican
+
+To install the development dependencies::
+
+    $ cd src/pelican
     $ pip install -r dev_requirements.txt
+
+To install Pelican and its dependencies::
+
     $ python setup.py develop
 
 Running the test suite
 ======================
 
 Each time you add a feature, there are two things to do regarding tests:
-checking that the existing tests pass, and adding tests for your new feature
+checking that the existing tests pass, and adding tests for the new feature
-or for the bug you're fixing.
+or bugfix.
 
 The tests live in "pelican/tests" and you can run them using the
 "discover" feature of unittest2::
 
     $ unit2 discover
 
-If you have made changes that affect the output of a pelican generated weblog,
+If you have made changes that affect the output of a Pelican-generated weblog,
 then you should update the output used by functional tests.
-To do so, you can use the 2 following commands::
+To do so, you can use the following two commands::
 
     $ LC_ALL="C" pelican -o tests/output/custom/ -s samples/pelican.conf.py \
         samples/content/
@@ -50,8 +61,9 @@ To do so, you can use the 2 following commands::
 Coding standards
 ================
 
-Try to respect what is described in the PEP8
+Try to respect what is described in the `PEP8 specification
-(http://www.python.org/dev/peps/pep-0008/) when providing patches. This can be
+<http://www.python.org/dev/peps/pep-0008/>`_ when providing patches. This can be
-eased by the pep8 tool (http://pypi.python.org/pypi/pep8) or by Flake8, which
+eased via the `pep8 <http://pypi.python.org/pypi/pep8>`_ or `flake8
-will give you some other cool hints about what's good or wrong
+<http://pypi.python.org/pypi/flake8/>`_ tools, the latter of which in
-(http://pypi.python.org/pypi/flake8/)
+particular will give you some useful hints about ways in which the 
+code/formatting can be improved.

docs/faq.rst

@@ -3,6 +3,33 @@ Frequently Asked Questions (FAQ)
 
 Here is a summary of the frequently asked questions for Pelican.
 
+What's the best way to communicate a problem, question, or suggestion?
+======================================================================
+
+If you have a problem, question, or suggestion, please start by striking up a
+conversation on `#pelican on Freenode <irc://irc.freenode.net/pelican>`_.
+Those who don't have an IRC client handy can jump in immediately via
+`IRC webchat <http://webchat.freenode.net/?channels=pelican&uio=d4>`_. Because
+of differing time zones, you may not get an immediate response to your question,
+but please be patient and stay logged into IRC — someone will almost always
+respond.
+
+If you are unable to resolve your issue or if you have a feature request, please
+refer to the `issue tracker <https://github.com/getpelican/pelican/issues>`_.
+
+How can I help?
+================
+
+There are several ways to help out. First, you can use Pelican and report any
+suggestions or problems you might have via IRC or the issue tracker.
+
+If you want to contribute, please fork `the git repository
+<https://github.com/getpelican/pelican/>`_, create a new feature branch, make
+your changes, and issue a pull request. Someone will review your changes as soon
+as possible. Please refer to the :ref:`contribute` section for more details.
+
+You can also contribute by creating themes and improving the documentation.
+
 Is it mandatory to have a configuration file?
 =============================================
 
@@ -25,19 +52,6 @@ How do I create my own theme?
 
 Please refer to :ref:`theming-pelican`.
 
-How can I help?
-================
-
-There are several ways to help out. First, you can use Pelican and report any
-suggestions or problems you might have on `the bugtracker
-<https://github.com/getpelican/pelican/issues>`_.
-
-If you want to contribute, please fork `the git repository
-<https://github.com/getpelican/pelican/>`_, make your changes, and issue
-a pull request. I'll review your changes as soon as possible.
-
-You can also contribute by creating themes and improving the documentation.
-
 I want to use Markdown, but I got an error.
 ===========================================
 
@@ -50,11 +64,11 @@ In case you don't have pip installed, consider installing it via::
 
     $ (sudo) easy_install pip
 
-How do I assign custom templates on a per page basis?
+How do I assign custom templates on a per-page basis?
 =====================================================
 
 It's as simple as adding an extra line of metadata to any pages or articles you
-want to have it's own template.
+want to have its own template.
 
     :template: template_name
 
@@ -66,30 +80,34 @@ What if I want to disable feed generation?
 
 To disable all feed generation set ``FEED_ATOM`` and ``FEED_RSS`` to ``None`` in
 your settings. Please note ``None`` and ``''`` are not the same thing. The
-word None should not be surrounded by quotes.
+word ``None`` should not be surrounded by quotes.
 
-I'm getting a warning about Feeds generated without SITEURL being set properly
+I'm getting a warning about feeds generated without SITEURL being set properly
 ==============================================================================
 
-`RSS and atom feeds require all URLs and links in them to be absolute <http://validator.w3.org/feed/docs/rss2.html#comments>`_.
+`RSS and Atom feeds require all URLs and links in them to be absolute
-In order to properly generate all URLs properly in pelican you will need to set
+<http://validator.w3.org/feed/docs/rss2.html#comments>`_.
-``SITEURL`` to the full path of your blog. By default, when using the ``make html``
+In order to properly generate all URLs properly in Pelican you will need to set
-to test build your site ``SITEURL`` is disabled so you should receive this
+``SITEURL`` to the full path of your blog. When using ``make html`` and the
-warning.
+default Makefile provided by the `pelican-quickstart` bootstrap script to test
-If configured properly no other make commands should have this message.
+build your site, it's normal to see this warning since ``SITEURL`` is 
+deliberately left undefined. If configured properly no other ``make`` commands
+should result in this warning.
 
-Feeds still are generated when this error comes up, but may not validate.
+Feeds are still generated when this warning is displayed but may not validate.
 
-My feeds are broken since I upgraded to 3.0
+My feeds are broken since I upgraded to Pelican 3.0
-===========================================
+===================================================
 
-Starting in 3.0 we changed the more confusing FEED options to say FEED_ATOM
+Starting in 3.0, some of the FEED setting names were changed to more explicitly
-like the RRS feed options. Here is an exact list of the changes::
+refer to the Atom feeds they inherently represent (much like the FEED_RSS
+setting names). Here is an exact list of the renamed setting names::
 
     FEED -> FEED_ATOM
     TAG_FEED -> TAG_FEED_ATOM
     CATEGORY_FEED -> CATEGORY_FEED_ATOM
 
-Older 2.x themes that referenced these may not link properly. Please update
+Older 2.x themes that referenced the old setting names may not link properly.
-your themes for 3 on. For an example of complete RSS headers and usage please
+In order to rectify this, please update your theme for compatibility with 3.0+
-check out the simple theme.
+by changing the relevant values in your template files. For an example of 
+complete feed headers and usage please check out the ``simple`` theme.

docs/index.rst

@@ -1,7 +1,7 @@
 Pelican
 #######
 
-Pelican is a simple weblog generator, written in Python.
+Pelican is a static site generator, written in Python.
 
 * Write your weblog entries directly with your editor of choice (vim!) in
   reStructuredText or Markdown
@@ -18,16 +18,16 @@ Pelican currently supports:
 * Comments, via an external service (Disqus). (Please note that while
   useful, Disqus is an external service, and thus the comment data will be
   somewhat outside of your control and potentially subject to data loss.)
-* Theming support (themes are created using `jinja2 <http://jinja.pocoo.org/>`_)
+* Theming support (themes are created using `Jinja2 <http://jinja.pocoo.org/>`_)
 * PDF generation of the articles/pages (optional)
 * Publication of articles in multiple languages
 * Atom/RSS feeds
 * Code syntax highlighting
-* Compilation of less css (optional)
+* Compilation of `LESS CSS <http://lesscss.org/>`_ (optional)
 * Import from WordPress, Dotclear, or RSS feeds
 * Integration with external tools: Twitter, Google Analytics, etc. (optional)
 
-Why the name "Pelican" ?
+Why the name "Pelican"?
 ========================
 
 Heh, you didn't notice? "Pelican" is an anagram for « Calepin » ;)
@@ -35,18 +35,18 @@ Heh, you didn't notice? "Pelican" is an anagram for « Calepin » ;)
 Source code
 ===========
 
-You can access the source code via git at http://github.com/getpelican/pelican/
+You can access the source code at: http://github.com/getpelican/pelican/
 
 Feedback / Contact us
 =====================
 
-If you want to see new features in Pelican, don't hesitate to tell me, to clone
+If you want to see new features in Pelican, don't hesitate to chime in, clone
 the repository, etc. That's open source, dude!
 
-Contact me at "alexis at notmyidea dot org" for any request/feedback! You can
+Send a message to "alexis at notmyidea dot org" with any requests/feedback! You
-also join the team at `#pelican on irc.freenode.org
+can also join the team at
-<irc://irc.freenode.net/pelican>`_
+`#pelican on Freenode <irc://irc.freenode.net/pelican>`_ (or if you don't have 
-(or if you don't have any IRC client, use `the webchat
+a IRC client handy, use `the webchat
 <http://webchat.freenode.net/?channels=pelican&uio=d4>`_)
 for quick feedback.
 

docs/pelican-themes.rst

@@ -162,5 +162,3 @@ See also
 
 -   http://docs.notmyidea.org/alexis/pelican/
 -   ``/usr/share/doc/pelican/`` if you have installed Pelican using the `APT repository <http://skami18.github.com/pelican-packages/>`_
-
-

docs/plugins.rst

@@ -78,13 +78,13 @@ Tag cloud
 Translation
 -----------
 
-Github Activity
+GitHub activity
 ---------------
 
 This plugin makes use of the ``feedparser`` library that you'll need to
 install.
 
-Set the ``GITHUB_ACTIVITY_FEED`` parameter to your Github activity feed.
+Set the ``GITHUB_ACTIVITY_FEED`` parameter to your GitHub activity feed.
 For example, my setting would look like::
 
      GITHUB_ACTIVITY_FEED = 'https://github.com/kpanic.atom'
@@ -107,4 +107,4 @@ variable, as in the example::
 
 
 ``github_activity`` is a list of lists. The first element is the title
-and the second element is the raw HTML from Github.
+and the second element is the raw HTML from GitHub.

docs/settings.rst

@@ -83,11 +83,10 @@ Setting name (default value)                                            What doe
 `TIMEZONE`                                                              The timezone used in the date information, to
                                                                         generate Atom and RSS feeds. See the "timezone"
                                                                         section below for more info.
-`TYPOGRIFY` (``False``)                                                 If set to true, some
+`TYPOGRIFY` (``False``)                                                 If set to True, several typographical improvements will be
-                                                                        additional transformations will be done on the
+                                                                        incorporated into the generated HTML via the `Typogrify
-                                                                        generated HTML, using the `Typogrify
                                                                         <http://static.mintchaos.com/projects/typogrify/>`_
-                                                                        library
+                                                                        library, which can be installed via: ``pip install typogrify``
 `LESS_GENERATOR` (``FALSE``)                                            Set to True or complete path to `lessc` (if not
                                                                         found in system PATH) to enable compiling less
                                                                         css files. Requires installation of `less css`_.