# HG changeset patch # User Oben Sonne # Date 1284058142 -7200 # Thu Sep 09 20:49:02 2010 +0200 # Node ID 5ab3f85dd93b3019ec390301f61c9ec54c892003 # Parent 64c3ed977f827362a72d5d7cb537b5adea2ca81c Update doc diff --git a/README b/README --- a/README +++ b/README @@ -1,12 +1,15 @@ -*- restructuredtext -*- +=============================================================================== Diggie -====== +=============================================================================== -*Diggie* is a `Django`_ wiki application. While it can be integrated into every -Django driven site, it's main use case is to run it as a local wiki -web application. *Diggie* ships with a command line utility which automatically -sets up a local Django site running *Diggie*:: +*Diggie* is a `Markdown`_ and `Django`_ driven wiki application. + +As a Django app, it can be integrated it in every Django driven site. However, +it's main use case is to run it as a personal local wiki application. *Diggie* +ships with a command line utility which automatically sets up a local Django +site running *Diggie*:: $ diggie /path/to/wiki --init --name MyWiki $ diggie /path/to/wiki --run @@ -15,10 +18,12 @@ Install *Diggie* by running ``easy_install diggie`` or ``pip install diggie``. +.. _Markdown: http://daringfireball.net/projects/markdown/ .. _Django: http://www.djangoproject.com/ +------------------------------------------------------------------------------- Using Diggie as a personal local wiki --------------------------------------- +------------------------------------------------------------------------------- This is easy! @@ -32,24 +37,30 @@ 3. Point your browser to http://localhost:4000 . -Run ``diggie --help`` to get some more actions and options. +The new wiki contains a help page about using a *Diggie* wiki. Structure of a local wiki -''''''''''''''''''''''''' +~~~~~~~~~~~~~~~~~~~~~~~~~ A new wiki at ``/path/to/wiki`` consists of the following files and directories: -- ``wiki.db``: sqlite3 database containing wiki pages -- ``templates/diggie``: symbolic link, just ignore this for now -- ``media/diggie``: symbolic link, just ignore this for now -- ``media/images``: image links refer to files located here -- ``media/math``: used to store rendered formula images +``wiki.db`` + An `SQLite`_ database containing wiki pages. +``media/images`` + Wiki image links refer to files located here (see in-wiki help for details). +``media/math`` + Used to store rendered formula images (see in-wiki help for details). -That is you can easily share you wiki across multiple computers using -services like *UbuntuOne* or *DropBox*. +The whole wiki s file based which makes it easy to share it across +multiple computers, e.g. using services like `UbuntuOne`_ or `Dropbox`_. +.. _SQLite: http://www.sqlite.org/ +.. _UbuntuOne: https://one.ubuntu.com/ +.. _Dropbox: http://www.dropbox.com/ + +------------------------------------------------------------------------------- Using Diggie in a Django powered site ----------------------------------------- +------------------------------------------------------------------------------- For a simple example, have a look into the Django site projects created by the tool *diggie* for local wikis. @@ -59,56 +70,69 @@ 1. Add ``diggie`` to ``INSTALLED_APPS`` in the project's ``settings.py``. -2. Create a symbolic link ``diggie`` in the project's template directory - pointing to ``/path/to/diggie-python-module/templates/diggie``. +2. Either add ``django.template.loaders.app_directories.Loader`` to + ``TEMPLATE_LOADERS`` in ``settings.py`` or link to + ``/path/to/diggie-python-module/templates/diggie`` from one of the + project's template locations. -3. Create a symbolic link ``diggie`` in the project's ``MEDIA_ROOT`` pointing - to ``/path/to/diggie-python-module/media/diggie``. - -4. Set *Diggie* specific options in the projects ``settings.py``: +3. Set *Diggie* specific options in the projects ``settings.py``: - +---------------------+--------------+------------------------------------+ - | Setting | Default | Description | - +=====================+==============+====================================+ - | ``DIGGIE_WIKINAME`` | ``"Diggie"`` | Name of the wiki. | - +---------------------+--------------+------------------------------------+ - | ``DIGGIE_MEDIA`` | ``""`` | Path relative to ``MEDIA_ROOT`` | - | | | (and ``MEDIA_URL``) to use for wiki| - | | | content files (e.g. images). Must | - | | | use *slashes*! The server needs | - | | | write access to | - | | | ``MEDIA_ROOT/DIGGIE_MEDIA/math`` | - | | | for saving rendered math images. | - +---------------------+--------------+------------------------------------+ - | ``DIGGIE_MDX`` | ``[]`` | List of additional or custom | - | | | markdown extensions. | - +---------------------+--------------+------------------------------------+ + ``DIGGIE_WIKINAME = "Diggie"`` + Name of the wiki. + + ``DIGGIE_MEDIA = ""`` + Path relative to ``MEDIA_ROOT`` (and ``MEDIA_URL``) to use for wiki + content files (e.g. images). Must use *slashes*! The server needs write + access to ``MEDIA_ROOT/DIGGIE_MEDIA/math`` for saving rendered math + images. + + ``DIGGIE_MDX = []`` + List of additional or custom markdown extensions. -5. Adjust your ``urls.py``, for instance:: +4. Adjust the project's ``urls.py``, for instance:: urlpatterns = patterns('', ... (r'diggie/^', include('diggie.urls')), ) -6. Sync the project's database:: +5. Sync the project's database:: $ python manage.py syncdb Finished. +------------------------------------------------------------------------------- Import and export ------------------ +------------------------------------------------------------------------------- The command line tool *diggie* can be used to import or export pages into or -from a *Diggie* wiki. +from a *Diggie* wiki. This is useful to backup wiki pages outside of an +database, migrate between incompatible *Diggie* versions or to migrate +pages from another wiki to a *Diggie* wiki or vice versa. + +Run ``diggie --help`` for details. + +------------------------------------------------------------------------------- +A disclaimer on browser support +------------------------------------------------------------------------------- -TODO +*Diggie* is a one-person free-time project. As that I'm not able to or willing +to check if *Diggie* runs equally pleasant in all browsers. Indeed *Diggie* +uses some rather new CSS and HTML features you'll probably won't find in older +browsers. +Personally I use it in Google Chrome 6. If you find something not working in +other browsers, feel free to fix this and share your patches by forking the +source repository. I'll happily integrate improvements, except dirty hacks for +old IE versions. + +=============================================================================== Changes -======= +=============================================================================== +------------------------------------------------------------------------------- Version 0.1 ------------ +------------------------------------------------------------------------------- - Initial release \ No newline at end of file