# HG changeset patch
# Parent d1b18afa823cedfccce1294f5b436f34c9822a77
diff -r d1b18afa823c README
--- a/README Fri Sep 30 00:26:34 2011 -0400
+++ b/README Fri Sep 30 00:29:43 2011 -0400
@@ -1,44 +1,190 @@
.. -*- restructuredtext -*-
-README for Sphinx
+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.
+.. note:: HgBlog assumes a level of familiarity with RST and Mercurial. You
+ can certainly use and enjoy using HgBlog if you've never used either one
+ of them. I recommend reviewing a `tutorial for Mercurial <http://2ze.us/o2M>`_
+ if you've never used it or are unfamiliar with how Mercurial affects your
- python setup.py build
- sudo python setup.py install
+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.
+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.
-Reading the docs
+Why?? Aren't There Enough Blog Engines Already?
+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
- cd doc
- sphinx-build . _build/html
+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.
-Then, direct your browser to ``_build/html/index.html``.
+What does HgBlog offer you that *should* be attractive?
-Or read them online at <http://sphinx.pocoo.org>.
+* **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:
+ * 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
+* **Redundancy**. Since every article you want to have on your blog must be
+ checked into Mercurial, a `distributed version control system <http://2ze.us/eJ>`_.
+ 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.
-To run the tests with the interpreter available as ``python``, use::
- make test
+* 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``
+* 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.
-If you want to use a different interpreter, e.g. ``python3``, use::
- PYTHON=python3 make test
-Send wishes, comments, patches, etc. to email@example.com.
+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 <http://2ze.us/m2M>`_
+ * Extract the ``.tar.gz`` file
+ * Run ``python setup.py install`` using the ``setup.py`` in the extracted directory
+* Using Mercurial::
+ hg qclone http://bitbucket.org/codekoala/hgblog
+ cd hgblog
+ hg qapply -a
+ python setup.py install
+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::
+All you need to do is:
+* Provide the directory on your filesystem that shall be used for your blogging
+* 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
+...to 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.
+If you feel like using Mercurial to clone your blog articles to another system,
+you might be interested in adding to the new repository the same hooks that are
+installed by the quickstart utility. First off, this requires HgBlog to be
+installed on the other system. Next, edit the ``.hg/hgrc`` file for the new
+ update.hgblog = python:hgblog.generate_html.htmlize_articles
+ commit.hgblog = python:hgblog.generate_html.htmlize_articles
+These hooks make it so the HTML version of your pages will be generated each
+time you commit changes to the local repository and each time you update your
+local repository using changesets pulled in from elsewhere.
+Generating HTML Without Committing
+I realize that there are probably several times you might want to have a gander
+at the resulting HTML for your ``.rst`` files at some point before committing
+changes to the repo. I've created a simple command to make this possible::
+You should be able to call that from anywhere within your blog's Mercurial
+repository, and your HTML files should be properly refreshed.
+* Add RSS feeds