@@ 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 @@ is all you need to get your local wiki u
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 @@ 2. Run::
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 @@ follows:
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