hgblog / readme.patch

# HG changeset patch
# Parent 73b7b304dd7cb436acbe3d17fdfa6c163b01e837

diff -r 73b7b304dd7c README
--- a/README	Fri Apr 23 12:23:54 2010 -0400
+++ b/README	Fri Apr 23 16:51:22 2010 -0400
@@ -1,33 +1,161 @@
 .. -*- restructuredtext -*-
-README for Sphinx
+HgBlog Readme
+HgBlog is a set of modifications to the Sphinx project to make it slightly more 
+suitable as a blogging engine.  It's built for those of us who love using
+reStructuredText markup to write documents.
-Use ````::
+The quickstart wizard handles setting up an HgBlog for you.  This includes all
+of the usual things that the Sphinx quickstart utility does, but it creates a
+Mercurial repository and installs a hook and intelligent ignores for you.  The
+hook will automatically convert the ``.rst`` files that Mercurial is tracking
+into HTML using Sphinx when you commit changes to the repository.
-    python build
-    sudo python install
+Additionally, when you pull changes in from a remote clone of the repository, 
+the hook will do the conversion just like when you commit locally.  You can set
+the hook up on remote clones as well.  The hook *only* converts ``.rst`` files
+that are tracked by Mercurial.  This means you can work on new blog articles 
+without committing them to the repository to have them not appear online.
+Why?? Aren't There Enough Blog Engines Already?
-Reading the docs
+Yes, there are.  And most of them rely on databases that require regular 
+maintenance and backup.  Databases can also slow down your blog.  HgBlog offers
+you a way to serve up your blog articles as static HTML without the overhead
+of requesting an object from a database, making it fit into a layout, etc.
+Any webserver should be perfectly capable of serving the content generated by
-After installing::
+I'm not saying there's anything wrong with database-backed blogs.  I maintain
+my own blog that is Django powered (and database-backed).  It works fine for
+me.  However, some people might not want to be confined to the rules imposed
+by a full-on blogging engine (whatever they may be).  People have all sorts of
+reasons for doing things differently.  Some people don't need a reason at all.
+It boils down to what works for you.
-    cd doc
-    sphinx-build . _build/html
+What does HgBlog offer you that *should* be attractive?
-Then, direct your browser to ``_build/html/index.html``.
+* **Speed**.  No need to deal with the formatting headaches of whatever 
+  WYSIWYG editor your blogging engine has dictated is the best.  Just use 
+  reStructuredText markup (which is quite easy to learn if you've never used
+  it before) and let Sphinx worry about formatting it.
+* **Consistency**.  Again, reStructuredText is a very simple format that will
+  produce consistent, nicely-formatted documents.
+* **Portability**.  Since HgBlog generates static HTML, you can put it on any
+  server.  In fact, you don't even need any server software--just a web
+  browser.  Also, Sphinx allows you to export your articles in several formats:
-Or read them online at <>.
+    * HTML, multiple files
+    * HTML, single file
+    * epub
+    * LaTeX
+    * LaTeX PDF
+    * Plain text
+    * man pages
+  With other tools, you can even turn your ``.rst`` files into PDF or ODT
+  documents.
+* **Redundancy**. Since every article you want to have on your blog must be
+  checked into Mercurial, a `distributed version control system <>`_.
+  This means that you can easily clone your blog to another system, which is
+  a very fast and effective way to backup your articles.  If the primary
+  "server" for your blog ever dies, you are likely to have at least one full,
+  up-to-date backup of your blog if you're using Mercurial as it's designed.
+Possible Workflows
+* You have a server which offers Python and SSH access, and you're allowed to 
+  install your own software within your home directory (or you have full root 
+  access to install elsewhere).  Run the quickstart utility on your server,
+  clone the repository onto your local machine, write articles, commit them, 
+  push them up to your server.  When you're ready for those articles to appear
+  online, simply run ``hg up`` on the repository on your server.  Make sure your 
+  webserver software is configured to serve static content from your ``build/html``
+  directory.
+* Use HgBlog to produce your own, personal wiki.  Keep notes on things you do at
+  work or projects you're currently working on.
+* Don't have a server that supports ASP, PHP, Ruby, Python, or whatever 
+  language you prefer?  Use HgBlog to compose your articles locally, commit
+  changes to the ``.rst`` files, and use an FTP program to upload the HTML
+  files to your hosting provider.
-Send wishes, comments, patches, etc. to
+I've developed and tested HgBlog using Linux, Python 2.6.4, Mercurial 1.5.1,
+Sphinx 1.0-pre, docutils 0.6, Jinja2 2.4.1, and Pygments 1.3.1.  However,
+Sphinx suggests the following version requirements.  I'm just being safe with
+my requirement on Mercurial's version.
+* Python 2.4+
+* docutils 0.4+
+* Jinja2 2.2+
+* Pygments 0.8+
+* Mercurial 1.5+
+There are several ways to install HgBlog:
+* Using ``pip`` (recommended)::
+    pip install -U hgblog
+* Using ``easy_install``::
+    easy_install hgblog
+* From the CheeseShop
+    * Download the ``.tar.gz`` file from `PyPI <>`_
+    * Extract the ``.tar.gz`` file
+    * Run ``python install`` using the ```` in the extracted directory
+* Using Mercurial::
+    hg qclone
+    cd hgblog
+    hg qapply -a
+    python install
+Getting Started
+HgBlog leverages the existing quickstart wizard for Sphinx projects.  There 
+are some modifications to reduce the number of steps required, so you should
+be able to be up and running within a minute using::
+    hgblog-quickstart
+All you need to do is:
+* Provide the directory on your filesystem that shall be used for your blogging
+  needs.
+* Provide a name for your blog
+* Provide your name
+* Select any extensions you may want to include in your blog
+Once you do that, you should have a few new directories, one of which will be 
+called ``source``.  This is where you should write your ``.rst`` articles.  When
+you're done working on a particular article, you can use::
+    hg add
+    hg ci
+ add and commit it to your Mercurial repository.  At this point, Sphinx will
+be asked to generate the HTML for your blog based on your ``.rst`` files.
+* Implement Disqus commenting
+* Add RSS feeds
+* Include a simple, static HTML web server for faster results
Tip: Use camelCasing e.g. ProjME to search for