Source

hgblog / readme.patch

# HG changeset patch
# Parent 717b554a4598d9666e902c4b6fc3ad7ab9398c2a

diff -r 717b554a4598 README
--- a/README	Sat Apr 24 21:51:29 2010 -0400
+++ b/README	Sat Apr 24 21:53:40 2010 -0400
@@ -1,33 +1,190 @@
 .. -*- restructuredtext -*-
 
-=================
-README for Sphinx
-=================
+=============
+HgBlog Readme
+=============
 
-Installing
-==========
+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 ``setup.py``::
+.. 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
+   life.
 
-    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?
+===============================================
 
-After installing::
+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
+HgBlog.
 
-    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
 
-Contributing
+  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 <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.
+
+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.
+
+Requirements
 ============
 
-Send wishes, comments, patches, etc. to sphinx-dev@googlegroups.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+
+
+Installation
+============
+
+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
+
+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
+
+...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
+repository::
+
+    [hooks]
+    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::
+
+    hgblog-refresh
+
+You should be able to call that from anywhere within your blog's Mercurial 
+repository, and your HTML files should be properly refreshed.
+
+TODOs
+=====
+
+* Add RSS feeds
+
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.