Update the docs to show how badly are changes needed.
authorRadek Czajka <radekczajka@nowoczesnapolska.org.pl>
Wed, 12 Feb 2014 15:27:48 +0000 (16:27 +0100)
committerRadek Czajka <radekczajka@nowoczesnapolska.org.pl>
Wed, 12 Feb 2014 15:27:48 +0000 (16:27 +0100)
.gitignore
README.md
doc/architecture.rst
doc/index.rst
doc/installation.rst
doc/publishing.rst [deleted file]
requirements-dev.txt
requirements.txt

index cceada8..35f07ab 100644 (file)
@@ -36,3 +36,4 @@ TAGS
 
 media
 search_index
 
 media
 search_index
+doc/_build
index 9b4f4a5..e9999ed 100644 (file)
--- a/README.md
+++ b/README.md
@@ -24,8 +24,7 @@ Dependencies
 ============
 
  * All packages listed in requirements.txt
 ============
 
  * All packages listed in requirements.txt
- * Python libraries from lib directory
- * Django applications from apps directory
+ * Sass>=3.2
 
 How to deploy (development version)
 =============
 
 How to deploy (development version)
 =============
index fd36de5..db5b698 100644 (file)
@@ -1,40 +1,65 @@
 Architecture overview
 =====================
 
 Architecture overview
 =====================
 
-Books
------
+Catalogue of books
+------------------
 
 
-Books are kept in the :py:class:`catalogue.models.Book` model.  Dublin Core
-metadata, read by :py:mod:`librarian.dcparser.BookInfo`, are put in the
-`extra_info` JSON field.
+Books are kept in the :py:class:`catalogue.models.Book` model.
 
 
-Authors, kinds, epochs, genres are kept in :py:class:`catalogue.models.Tag`
-model with `category` field set to appriopriate value.
+Books have fragments, annotated  with themes. Those are kept in the
+:py:class:`catalogue.models.Fragment` model.
 
 
-:py:class:`catalogue.models.Tag` also contains :ref:`user-shelves`
-and :ref:`parent-relations`.
+Both ``Books`` and ``Fragments`` can have ``Tags``, which are
+:py:class:`catalogue.models.Tag` objects.
 
 
+What are ``Tags`` used for?
+---------------------------
 
 
-User shelves
-------------
+Each ``Tag`` objects has a ``category`` field specyfying its meaning.
+The categories are enumerated in :py:const:`catalogue.models.TAG_CATEGORIES`.
 
 
-User shelves (or tags on user's shelf) are just :py:class:`catalogue.models.Tag`
-objects with ``category='set'`` and ``user`` set to the owner. Shelves' slugs
-are generated automatically using :py:fun:`catalogue.utils.get_random_hash`.
+Tags are used for:
 
 
+* Keeping browsable metadata. Each ``Book`` can have any number of tags
+  of categories: ``author``, ``epoch``, ``kind``, ``genre``.
+  Each ``Fragment`` of a book has all of those, 
+  and also a number of ``theme`` tags.
+* User shelves. A User can put a ``Book`` on a shelf and add some labels
+  by adding a number of ``set`` tags to it. A book put on a shelf without
+  any labels has a Tag with an empty name.
+* Denoting :ref:`ancestor-descendant-relations` using ``book`` tags. 
 
 
-Parent relations
-----------------
 
 
-The source of parent relations is the
-:py:class:`librarian.dcparser.BookInfo.parts` metadata.
+.. _ancestor-descendant-relations:
 
 
-Parent relations are kept primarily in the :py:attribute:`catalogue.models.Book.parent`
-and :py:attribute:`catalogue.models.Book.parent_number` fields.
+Relations between ``Books``, ``Fragments`` and other ``Books``
+--------------------------------------------------------------
 
 
-They're also cached as :py:class:`Tag <catalogue.models.Tag>` relations.
-Each book has its tag (with :py:attribute:`slug <catalogue.models.Book.slug>`
-starting with ``l-``).  All of book's descendants (NOT the book
-itself) have its tag attached.
+Obviously, every ``Fragment`` comes from a particular ``Book``. This
+relation is expressed with the Fragment's ``book`` field.
 
 
-Arguably, this scheme has some potential for inconsistency.
+The source of parent-child relations between ``Books`` is
+the ``dc:relation.hasPart`` metadata field, exposed by
+:py:class:`librarian.dcparser.BookInfo` as ``parts``. This relation
+and the order of children of one parent is expressed with the child
+book's ``parent`` and ``parent_number`` fields.
+
+But aside from that, Tags are used for managing those relationships, too.
+
+Every ``Book`` has a matching `l-tag`. It's a ``Tag`` of category
+``book`` and matching slug with an added 'l-' prefix (the prefix
+is superfluous and we should remove it as some point, as it was only
+needed when tag slugs had to be unique).
+
+The `l-tag` of a ``Book`` is used on:
+
+* all of the book's fragments,
+* all of the book's descendants,
+* all of the book's descendants' fragments.
+
+This is used for:
+
+* finding fragments of a given theme in books with a given user label,
+* on a filtered book list (i.e., author's page), for eliminating
+  descendants, if an ancestor is already on the list,
+* when calculating tag book counts, for eliminating descendants as above,
index 0631446..0c2d1fd 100644 (file)
@@ -10,7 +10,6 @@ Welcome to Wolne Lektury's documentation!
    :maxdepth: 2
 
    installation
    :maxdepth: 2
 
    installation
-   publishing   
    architecture
    reference
 
    architecture
    reference
 
index 78ca3cc..32e46e5 100644 (file)
@@ -6,37 +6,33 @@ Requirements
 ------------
 
 * `Python 2.6+ <http://python.org>`_
 ------------
 
 * `Python 2.6+ <http://python.org>`_
-* Everyting from the ``requirements.txt`` file
+* Python requiremets: ``pip install -r requirements.txt``
 * a library for your database of choice
   (see `DBs supported by Django <http://docs.djangoproject.com/en/dev/topics/install/#get-your-database-running>`_)
 * a library for your database of choice
   (see `DBs supported by Django <http://docs.djangoproject.com/en/dev/topics/install/#get-your-database-running>`_)
-* `pyLucene <https://github.com/fnp/pylucene/>`_ for search
-* Librarian dependencies for generating PDF and MOBI files, 
+* `Sass <http://sass-lang.com>`_ >= 3.2 for parsing SCSS stylesheets
+* Librarian (bundled as a git submodule, remember to ``git submodule update --init``
+* Librarian has more dependencies if you want to build PDF and MOBI files, 
   see lib/librarian/README.md
   see lib/librarian/README.md
-
-
-Installation
-------------
-Installing database::
-
-    cd wolnelektury
-    ./manage.py syncdb
-    ./manage.py migrate
+* `Solr <https://lucene.apache.org/solr/>`_ server if you want to search
 
 
 Running
 -------
 
 
 Running
 -------
+Set up the database with::
+
+    ./manage.py syncdb --migrate
 
 
-You can run the server with::
+Run the dev server with::
 
     ./manage.py runserver
 
 
     ./manage.py runserver
 
-If you want to run lengthy tasks (like generating e-book files) in a seperate
-Celery process (this is the default), you'll also need to run:
+Some tasks (like generating e-books) run in a seperate
+Celery process by default, so you'll also need to run::
 
     ./manage.py celeryd --loglevel=INFO
 
 
     ./manage.py celeryd --loglevel=INFO
 
-If you don't want to run a separate Celery daemon, make sure you set this
-option in your ``localsettings.py``::
+Or, if you don't want to run a separate Celery daemon, set this
+in your ``localsettings.py``::
 
     CELERY_ALWAYS_EAGER = True
 
 
     CELERY_ALWAYS_EAGER = True
 
@@ -45,16 +41,22 @@ Deployment
 ----------
 Setup your server in fabfile.py and do::
 
 ----------
 Setup your server in fabfile.py and do::
 
-    fab <your_server_name> setup
+    fab <your_server_name> deploy
 
 
-Aside from uploading a current (git's HEAD) version of the app this will also
-download all dependencies into a `virtualenv <http://www.virtualenv.org>`_, 
-create a VHost and WSGI files for running with Apache and mod_wsgi, and
-a celery config file for `supervisord <http://supervisord.org/>`_.
+Initial deploy will stop and ask you to provide a localsettings.py file.
+A sample localsettings.py will be put on your server, as well as
+sample configuration for `Nginx <http://nginx.org/>`_,
+`Gunicorn <http://gunicorn.org/>`_ and
+`Supervisord <http://supervisord.org/>`_.
 
 
-To deploy a new version into an existing setup, do:
 
 
-    fab <your_server_name> deploy
+Publishing books
+----------------
+
+Books are represented as XML files.
+You can import XML files from a directory by running::
+
+    ./manage.py importbooks ../books
 
 
-This will also check for new dependencied, migrate your app and restart the
-WSGI server and Celery under supervisord.
+Or you can publish a single XML by using publishing form in admin,
+or the publishing API.
diff --git a/doc/publishing.rst b/doc/publishing.rst
deleted file mode 100644 (file)
index 5701738..0000000
+++ /dev/null
@@ -1,9 +0,0 @@
-Publishing books
-================
-
-You can import XML files from a directory by running::
-
-    ./manage.py importbooks ../books
-
-You can publish a single XML by using publishing form in admin,
-or the publishing API.
\ No newline at end of file
index bf15f80..739b6bf 100644 (file)
@@ -4,3 +4,4 @@ django-debug-toolbar
 polib
 BabelDjango
 Fabric
 polib
 BabelDjango
 Fabric
+sphinx
index 3ed01b3..f4de6b9 100644 (file)
@@ -16,7 +16,6 @@ django-picklefield
 -e git+git://github.com/rczajka/django-allauth.git@4ecda71b81f9311dea4febe1d2d0105f23c642c7#egg=django-allauth
 
 pytz
 -e git+git://github.com/rczajka/django-allauth.git@4ecda71b81f9311dea4febe1d2d0105f23c642c7#egg=django-allauth
 
 pytz
-pyScss
 
 # Some contrib apps still need it
 simplejson
 
 # Some contrib apps still need it
 simplejson