Commits

Luke Plant committed f6fcf07

updated README

Comments (0)

Files changed (1)

bibleverses/README

+= Bible Memorisation Project =
 
-Scripts in here:
- - read in data that is entered as YAML data in Wiki (BibleMemorisationYaml)
- - parse into Python
- - output data into another Wiki page - BibleMemorisationDone
+== Main concepts ==
+
+This is a system to help me create Bible memorisation schemes for
+myself and others.  The ultimate aim is to create lists of verse which
+cover a large range of topics, and have a few comments about the
+relevance of the supplied verses to different topics.  To produce this
+list, a number of data sources are used.  All data sources are stored
+as YAML text documents, which makes it very easy for unskilled people
+to add to them, and to extend the capabilities.
+
+The following sources are used:
+
+- Verse list:
+  - source: BibleMemorisationYaml
+  - Stores a list of verse references and information about the
+    categories it belongs to.  Each category entry has a level
+    and a comment.
+  - It also can store the actual text of the verse, for various
+    different versions.  If these are missing, the ESV version
+    can be automatically pulled in.  However, if a fraction of a verse
+    is wanted, then the text must be supplied.
+
+- Topic list:
+  - source: BibleMemorisationTopicYaml
+  - Stores a tree of topics that I am aiming to have memory verses
+    for.
+
+- Scheme list:
+  - source: BibleMemorisationSchemeYaml
+  - Stores a list of scheme definitions.  These are used in
+    conjunction with the topic tree and verse list to build
+    schemes, which end up as list of verses.
+
+Once these sources have been parsed into memory, the 'read.py' module
+arranges them into more useful Python data structures.  The 'build.py'
+module contains functions for building schemes.  The 'update.py'
+module is used to regenerate wiki pages/web pages from this data.
+
+== Data ==
+
+In my own system, this YAML is stored in a personal wiki.  A dump of
+this data is found in ./yaml .  When this data is converted into
+schemes, the resulting data is written to two places:
+
+ - different pages in my wiki
+ - HTML pages for publishing.
+
+To enable other developers to work on this project, it is possible to
+use a different 'backend' for retrieving the YAML from the ./yaml
+directory instead of the wiki database.  It is also possible to
+disable writing out to the wiki.  This is easy to do just by editing
+the config.py file.
+
+== Requirements ==
+
+ - Django library on your PYTHONPATH somewhere
+ - the parent 'lukeplant_me_uk' directory on your PYTHONPATH
+   (this is needed due to the way that Django needs to be able to look
+   for the 'templatetags' library used for rendering the HTML pages)
+ - libsword and it's Python swig bindings, and the ESV module
+   installed -- this is used to retrieve verses that are missing
+   from the sources
+ 
+
+== Usage ==
+
+First, configure by editing config.py, as mentioned above.
+
+The main front end is the 'update.py' script.  Just run:
+
+ python update.py