README.rst

   1 ========
   2 gitology
   3 ========
   4
   5 Note
   6 ----
   7
   8 This is RestructuredText_ document, and it can be viewed by using package
   9 restview_ (Command to use: ``restview --css=default.css *.rst``, to install:
  10 `sudo easy_install restview`).
  11
  12 Development Note
  13 ----------------
  14
  15 Use ``python setup.py develop`` to install instead of usual
  16 ``python setup.py install``.
  17
  18 git+openid based wiki/blog/photo-album
  19 ---------------------------------------
  20
  21 git file structure:
  22     /blocked-authors.txt contains openid of each blocked
  23     commenter/rater whatever.
  24
  25     /editors.txt: these ppl can do anything. [openids]
  26
  27 versioned-document, type:
  28     these pages are maintained in git.
  29     each page is identified as a folder:
  30     /document/some-name/ [somename is unique]
  31     index: index.html/index.rst
  32     summary: summary.html/summary.rst
  33     meta.json?
  34
  35     #. tags: tag1, tag2 [this is the master list]
  36     #. title:
  37     #. title-slug:
  38     #. container: blog@/some/date/ or wiki@label or
  39        album or photo@albumname
  40     #. is_private
  41
  42     dependencies:
  43         /document/some-name/file.gif etc
  44
  45     comment:
  46         /document/some-name/comment/1.rst, 1.meta. comments are
  47         threaded: /1.comment, /1/1.comment, 1/2.comment,
  48         1/1/1.comment, comments are rated.
  49         x.meta: author, timestamp, ratings: [(rater, rating), ], flagged etc.
  50
  51 blog, link-blog:
  52     /blog/year/month/date.list: containing document names timestamp and document name pairs.
  53     /blog/label/python.txt: containing document names. [this file is auto generated].
  54
  55 wiki:
  56     /wiki/some-name.txt. containing: /document/some-name/
  57     /wiki/mysql/insert/: containing: /document/mysql@insert/
  58
  59 photos:
  60     /photos/album.txt:
  61         all photos belong to albums.
  62         album and photos are both documents, in album, index.html is
  63         generated manually, and it contains a file: photos.txt containing
  64         /document/photo-name/
  65
  66 cheatsheets/keynote:
  67     /notes/name.txt
  68     /notes/name/something.txt
  69     /notes/name/something-else.txt
  70
  71 tools:
  72 ------
  73 * gitology init
  74 * gitology start document_name. creates a new document.
  75 * gitology grep, ls, cd, find [coz documents may be organized in subdirs]
  76 * gitology blog document_name: blogs the given document.
  77 * gitology link url tag1, tag2: takes description on stdin. # utility function
  78 * gitology sync: updated blog labels file, and other files as needed.
  79 * gitology wiki document_name: creates wiki link for a document.
  80 * gitology create-album: creates a new album.
  81 * gitology add-photo photo, album: adds the photo to the specified album.
  82   [photo can be either photo.gif or a document name].
  83
  84 implementation details:
  85 -----------------------
  86
  87 gitology shud be a easy_install-able app, and will provide:
  88 * command line tools
  89 * django apps: gitology_blog, gitology_wiki, gitology_album and so on.
  90
  91 gitology can be installed system wide and users can configure it as per
  92 their preferences. preferences are stored in ~/.gitologyrc.
  93
  94 on preferences:
  95     ideally a user shud be able to work with more than on gitology
  96     instances, selectable based on env variable, if more than one
  97     instances exist.
  98
  99     export GITOLOGY_CONFIG_FILE=".filenamerc"
 100
 101     .gitologyrc config file.
 102
 103     configuration:
 104
 105     * repo-path: where git repo is located
 106     * remote: remote where git shud push after commits if required.
 107
 108 there is a lib. import gitology. it handles config parsing. it handles
 109 reading and writing documents. it handles blog, comments, wiki, etc. and
 110 it handles versioning.
 111
 112 gitology.document.Document is the document abstraction.
 113
 114 Basic info:
 115     Document.index, Document.index_name, Document.format, Document.raw_index,
 116     Document.summary_content, Document.summary_name, Document.summary_raw,
 117     Document.meta.title, Document.meta.title_slug, Document.meta.tags,
 118     Document.meta.container, Document.meta.is_private.
 119
 120 dependency handling:
 121     Document.deps: key==filename, content==content of file, url, mime_type
 122
 123 comments:
 124     Document.replies: list of Comment. Comment.title, Comment.content,
 125     Comment.content_raw, Comment.openid, Comment.poster_name,
 126     Comment.poster_email, Comment.poster_url, Comment.posted_on
 127     Comment.ratings: array of (openid, rating). Comment.score,
 128     Comment.replies. Comment.versions [CommentRevision(ts, content, title)]
 129
 130 Versioning:
 131     Document.versions: [DocumentRevision(ts, title, content)]
 132
 133 methods:
 134     * Document.update_title(title)
 135     * Document.update_content(content, type=rst) => changing type raises exception.
 136     * Document.add_comment(author, content, title=None, in_reply_to=None, timestamp=None)
 137
 138 gitology.blog.Post:
 139     Post.document, Post.title, Post.posted_on, Post.slug, Post.content
 140     Post.make_private(), Post.make_public()
 141
 142 gitology.blog:
 143     * blog_document(Document, published_on=None)
 144     * get_post_by_slug(slug)
 145     * get_posts(year=None, month=None, day=None, count=10, start=0)
 146     * get_post_count(year=None, month=None, day=None)
 147
 148 gitolog.wiki.Page:
 149     Page.document, Page.name, Page.content
 150
 151 gitology.wiki:
 152     * wiki_this_document(Document, published_on=None)
 153     * get_page_by_name(name)
 154     * page_exists(name)
 155
 156 gitology.notes.Note:
 157     * Note.children[ordereddict], Note.title, Note.content.
 158
 159 gitology.notes:
 160     * get_note_by_path("/mysql/insert/")
 161     * get_children("path", span_tree=False) :: path can be "" or "/" to indicate root.
 162
 163 sample filestructure:
 164 ---------------------
 165
 166 ::
 167
 168    ./wiki
 169    ./wiki/python.txt
 170    ./blocked-authors.txt
 171    ./editors.txt
 172    ./documents
 173    ./documents/23
 174    ./documents/23/ee
 175    ./documents/23/ee/python
 176    ./documents/23/ee/python/index.rst
 177    ./documents/23/ee/python/comments
 178    ./documents/23/ee/python/comments/1.rst
 179    ./documents/23/ee/python/comments/1.meta
 180    ./documents/23/ee/python/meta.json
 181    ./notebooks
 182    ./notebooks/work
 183    ./notebooks/personal
 184    ./notebooks/personal/swideas.txt
 185    ./notebooks/personal/swideas
 186    ./albums
 187    ./albums/lonawala.txt
 188    ./blogs
 189    ./blogs/link
 190    ./blogs/main
 191    ./blogs/main/labels
 192    ./blogs/main/labels/python.lst
 193    ./blogs/main/2008
 194    ./blogs/main/2008/07
 195    ./blogs/main/2008/07/08.lst
 196
 197 .. _RestructuredText:
 198    http://docutils.sourceforge.net/docs/user/rst/quickref.html
 199 .. _restview: http://mg.pov.lt/restview/