From aae232dcf008ab39db553bc1b20573fa00e3b191 Mon Sep 17 00:00:00 2001 From: Radek Czajka Date: Wed, 12 Feb 2014 16:27:48 +0100 Subject: [PATCH] Update the docs to show how badly are changes needed. --- .gitignore | 1 + README.md | 3 +- doc/architecture.rst | 75 +++++++++++++++++++++++++++++--------------- doc/index.rst | 1 - doc/installation.rst | 54 ++++++++++++++++--------------- doc/publishing.rst | 9 ------ requirements-dev.txt | 1 + requirements.txt | 1 - 8 files changed, 81 insertions(+), 64 deletions(-) delete mode 100644 doc/publishing.rst diff --git a/.gitignore b/.gitignore index cceada847..35f07ab99 100644 --- a/.gitignore +++ b/.gitignore @@ -36,3 +36,4 @@ TAGS media search_index +doc/_build diff --git a/README.md b/README.md index 9b4f4a51e..e9999ed37 100644 --- a/README.md +++ b/README.md @@ -24,8 +24,7 @@ Dependencies ============ * All packages listed in requirements.txt - * Python libraries from lib directory - * Django applications from apps directory + * Sass>=3.2 How to deploy (development version) ============= diff --git a/doc/architecture.rst b/doc/architecture.rst index fd36de5a6..db5b6989d 100644 --- a/doc/architecture.rst +++ b/doc/architecture.rst @@ -1,40 +1,65 @@ 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 ` relations. -Each book has its tag (with :py:attribute:`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, diff --git a/doc/index.rst b/doc/index.rst index 06314468f..0c2d1fdfe 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -10,7 +10,6 @@ Welcome to Wolne Lektury's documentation! :maxdepth: 2 installation - publishing architecture reference diff --git a/doc/installation.rst b/doc/installation.rst index 78ca3ccbb..32e46e58c 100644 --- a/doc/installation.rst +++ b/doc/installation.rst @@ -6,37 +6,33 @@ Requirements ------------ * `Python 2.6+ `_ -* 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 `_) -* `pyLucene `_ for search -* Librarian dependencies for generating PDF and MOBI files, +* `Sass `_ >= 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 - - -Installation ------------- -Installing database:: - - cd wolnelektury - ./manage.py syncdb - ./manage.py migrate +* `Solr `_ server if you want to search Running ------- +Set up the database with:: + + ./manage.py syncdb --migrate -You can run the server with:: +Run the dev server with:: ./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 -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 @@ -45,16 +41,22 @@ Deployment ---------- Setup your server in fabfile.py and do:: - fab setup + fab deploy -Aside from uploading a current (git's HEAD) version of the app this will also -download all dependencies into a `virtualenv `_, -create a VHost and WSGI files for running with Apache and mod_wsgi, and -a celery config file for `supervisord `_. +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 `_, +`Gunicorn `_ and +`Supervisord `_. -To deploy a new version into an existing setup, do: - fab 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 index 57017380a..000000000 --- a/doc/publishing.rst +++ /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 diff --git a/requirements-dev.txt b/requirements-dev.txt index bf15f80bf..739b6bfc6 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -4,3 +4,4 @@ django-debug-toolbar polib BabelDjango Fabric +sphinx diff --git a/requirements.txt b/requirements.txt index 3ed01b3dd..f4de6b937 100644 --- a/requirements.txt +++ b/requirements.txt @@ -16,7 +16,6 @@ django-picklefield -e git+git://github.com/rczajka/django-allauth.git@4ecda71b81f9311dea4febe1d2d0105f23c642c7#egg=django-allauth pytz -pyScss # Some contrib apps still need it simplejson -- 2.20.1