Fetching latest commit…
Cannot retrieve the latest commit at this time.
|Failed to load latest commit information.|
# 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 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+ + +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 +