Start updating docs.

Change default config to ease basic setup: DEBUG is True, Celery and search are disabled.

diff --git a/README.md b/README.md
index 13c0ed2..139cccc 100644 (file)
--- a/README.md
+++ b/README.md
@@ -1,3 +1,14 @@
+# Wolne Lektury
+
+![Wolne Lektury](src/wolnelektury/static/img/logo-bez.png)
+
+
+Wolne Lektury is a free internet library maintained by Modern Poland Foundation.
+
+It's a service based on [Django](https://www.djangoproject.com/), using
+[Librarian](https://git.mdrn.pl/librarian.git) to publish books in various formats.
+
+

 License
 -------
 
 License
 -------
 


@@ -20,12 +31,13 @@ License
     You should have received a copy of the GNU Affero General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
     
     You should have received a copy of the GNU Affero General Public License
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
     

+

 Dependencies
 ============
 
 Dependencies
 ============
 

- * Python 3.4+
+ * Python 3.5-3.7

  * All packages listed in requirements.txt
  * All packages listed in requirements.txt

- * Sass>=3.2
+

 
 How to deploy (development version)
 =============
 
 How to deploy (development version)
 =============


@@ -55,6 +67,7 @@ How to deploy (development version)
    Translation strings are based on gettext and can be found under 'locale' dir.
    There are also JavaScript files for jQuery countdown plugin (static/js/jquery.countdown-*.js).
 
    Translation strings are based on gettext and can be found under 'locale' dir.
    There are also JavaScript files for jQuery countdown plugin (static/js/jquery.countdown-*.js).
 

+

 Bundled software
 ================
 
 Bundled software
 ================
 


@@ -79,7 +92,6 @@ Bundled software
   with relevant attribution and licensing
   
 
   with relevant attribution and licensing
   
 

-

 Authors
 =======
  * Marek Stępniowski  <marek@stepniowski.com>
 Authors
 =======
  * Marek Stępniowski  <marek@stepniowski.com>

diff --git a/doc/advanced-setup.rst b/doc/advanced-setup.rst
new file mode 100644 (file)
index 0000000..97a82c2
--- /dev/null
+++ b/doc/advanced-setup.rst
@@ -0,0 +1,51 @@
+==============
+Advanced setup
+==============
+
+Changing database backend
+-------------------------
+
+The project does not rely on any features specific to a database backend, so you can choose
+any of the :django:`backends supported by Django <topics/install/#get-your-database-running>`.
+
+
+Search engine
+-------------
+
+.. todo::
+
+   Setting up Solr to be documented.
+    
+
+Task queue
+----------
+
+Some tasks (like generating e-books) run in a seperate
+Celery process by default, so you'll also need to run::
+
+    celery -A wolnelektury worker --loglevel=INFO
+
+
+
+Generating PDF files
+--------------------
+
+.. todo::
+
+   To be documented.
+
+
+Generating EPUB files
+---------------------
+
+.. todo::
+
+   To be documented.
+
+
+Generating MOBI files
+---------------------
+
+.. todo::
+
+   To be documented.

diff --git a/doc/basic-setup.rst b/doc/basic-setup.rst
new file mode 100644 (file)
index 0000000..f232aa6
--- /dev/null
+++ b/doc/basic-setup.rst
@@ -0,0 +1,53 @@
+===========
+Basic setup
+===========
+
+Wolne Lektury is a `Django <https://www.djangoproject.com/>`_ project.
+
+If you're new to Django, we strongly recommend you complete
+the `Django Girls Tutorial <https://tutorial.djangogirls.org/en/>`_ and/or
+the official :django:`Django Tutorial <getting-started>`
+to learn about setting up a Python virtual environment and general structure
+of a Django project.
+
+Getting started
+---------------
+
+Once you have your Python (version at least 3.5) installed, virtualenv created,
+and the source code of Wolne Lektury checked out to a directory, then the most
+basic setup is as easy as:
+
+    $ pip install -r requirements/requirements.txt
+
+After that, you should be able to run tests:
+
+    $ src/manage.py test
+
+And migrate the database and run the development server:
+
+    $ src/manage.py migrate
+    $ src/manage.py runserver
+
+
+Publishing books
+----------------
+
+Books are represented as XML files.
+You can download some books as source XML files and import them
+into your instance either by using the admin interface,
+or by running::
+
+    src/manage.py importbooks your-directory-with-xml-files
+
+
+What's next?
+------------
+
+This basic setup:
+
+* uses a SQLite file as a database,
+* has search disabled,
+* does not generate PDF, EPUB or MOBI files from books,
+* will generate TXT, HTML, FB2 and cover image files, but will not use a task queue.
+
+In the next section, you'll see what additional setup is needed to solve these issues.

diff --git a/doc/conf.py b/doc/conf.py
index 1e8ba28..7c09286 100644 (file)
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -32,7 +32,7 @@ django.setup()
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

-extensions = ['sphinx.ext.autodoc', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.extlinks', 'sphinx.ext.intersphinx', 'sphinx.ext.todo', 'sphinx.ext.coverage', 'sphinx.ext.viewcode']

 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']


@@ -222,6 +222,9 @@ man_pages = [
      ['Fundacja Nowoczesna Polska'], 1)
 ]
 
      ['Fundacja Nowoczesna Polska'], 1)
 ]
 

-
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'http://docs.python.org/': None}
+extlinks = {
+    'django': (
+        'https://docs.djangoproject.com/en/%d.%d/%%s' % django.VERSION[:2],
+        None
+    )
+}

diff --git a/doc/deployment.rst b/doc/deployment.rst
new file mode 100644 (file)
index 0000000..fc4514f
--- /dev/null
+++ b/doc/deployment.rst
@@ -0,0 +1,4 @@
+==========
+Deployment
+==========
+

diff --git a/doc/index.rst b/doc/index.rst
index 0c2d1fd..9018fb0 100644 (file)
--- a/doc/index.rst
+++ b/doc/index.rst
@@ -9,7 +9,9 @@ Welcome to Wolne Lektury's documentation!
 .. toctree::
    :maxdepth: 2
 
 .. toctree::
    :maxdepth: 2
 

-   installation
+   basic-setup
+   advanced-setup
+   deployment

    architecture
    reference
 
    architecture
    reference
 

diff --git a/doc/installation.rst b/doc/installation.rst
deleted file mode 100644 (file)
index 81ef4de..0000000
--- a/doc/installation.rst
+++ /dev/null
@@ -1,54 +0,0 @@
-=====
-Setup
-=====
-
-Requirements
-------------
-
-* `Python 3.5-3.7 <http://python.org>`_
-* Python requiremets: ``pip install -r requirements/requirements.txt``
-* a library for your database of choice
-  (see `DBs supported by Django <https://docs.djangoproject.com/en/dev/topics/install/#get-your-database-running>`_)
-* `Sass <http://sass-lang.com>`_ >= 3.2 for parsing SCSS stylesheets
-* Librarian has more dependencies if you want to build PDF and MOBI files, 
-  see lib/librarian/README.md
-* `Solr <https://lucene.apache.org/solr/>`_ server if you want to search
-
-
-Running
--------
-Set up the database with::
-
-    ./manage.py migrate
-
-Run the dev server with::
-
-    ./manage.py runserver
-
-Some tasks (like generating e-books) run in a seperate
-Celery process by default, so you'll also need to run::
-
-    celery -A wolnelektury worker --loglevel=INFO
-
-Or, if you don't want to run a separate Celery daemon, set this
-in your ``localsettings.py``::
-
-    CELERY_ALWAYS_EAGER = True
-
-
-Deployment
-----------
-
-TODO
-
-
-Publishing books
-----------------
-
-Books are represented as XML files.
-You can import XML files from a directory by running::
-
-    ./manage.py importbooks ../books
-
-Or you can publish a single XML by using publishing form in admin,
-or the publishing API.

diff --git a/requirements/requirements.txt b/requirements/requirements.txt
index b3fc758..ce0b5e9 100644 (file)
--- a/requirements/requirements.txt
+++ b/requirements/requirements.txt
@@ -8,6 +8,7 @@ fnpdjango==0.4
 # Because of https://github.com/jazzband/django-pipeline/pull/682 + https://github.com/getsentry/sentry-python/issues/436
 -e git+https://github.com/jazzband/django-pipeline@3cd2f93bb47bf8d34447e13ff691f7027e7b07a2#egg=django-pipeline
 
 # Because of https://github.com/jazzband/django-pipeline/pull/682 + https://github.com/getsentry/sentry-python/issues/436
 -e git+https://github.com/jazzband/django-pipeline@3cd2f93bb47bf8d34447e13ff691f7027e7b07a2#egg=django-pipeline
 

+libsasscompiler==0.1.5

 
 jsmin
 fnp-django-pagination==2.2.3
 
 jsmin
 fnp-django-pagination==2.2.3


@@ -50,9 +51,6 @@ librarian==1.7.4
 # celery tasks
 celery[redis]==4.3.0
 
 # celery tasks
 celery[redis]==4.3.0
 

-# spell checking
-pyenchant
-

 # OAI-PMH
 pyoai==2.5.0
 
 # OAI-PMH
 pyoai==2.5.0
 

diff --git a/src/catalogue/models/book.py b/src/catalogue/models/book.py
index 9116a46..5dbda47 100644 (file)
--- a/src/catalogue/models/book.py
+++ b/src/catalogue/models/book.py
@@ -237,6 +237,12 @@ class Book(models.Model):
 
     @staticmethod
     def format_audio_length(seconds):
 
     @staticmethod
     def format_audio_length(seconds):

+        """
+        >>> Book.format_audio_length(1)
+        '0:01'
+        >>> Book.format_audio_length(3661)
+        '1:01:01'
+        """

         if seconds < 60*60:
             minutes = seconds // 60
             seconds = seconds % 60
         if seconds < 60*60:
             minutes = seconds // 60
             seconds = seconds % 60

diff --git a/src/catalogue/tests/test_doctests.py b/src/catalogue/tests/test_doctests.py
new file mode 100644 (file)
index 0000000..0225e59
--- /dev/null
+++ b/src/catalogue/tests/test_doctests.py
@@ -0,0 +1,8 @@
+import doctest
+import unittest
+import catalogue.models.book
+
+
+def load_tests(loader, tests, ignore):
+    tests.addTests(doctest.DocTestSuite(catalogue.models.book))
+    return tests

diff --git a/src/wolnelektury/settings/__init__.py b/src/wolnelektury/settings/__init__.py
index 8e0815b..f8451cc 100644 (file)
--- a/src/wolnelektury/settings/__init__.py
+++ b/src/wolnelektury/settings/__init__.py
@@ -23,6 +23,22 @@ except ImportError:
     pass
 
 
     pass
 
 

+# If Celery broker not configured, enable always-eager mode.
+try:
+    CELERY_BROKER_URL
+except NameError:
+    CELERY_TASK_ALWAYS_EAGER = True
+
+
+# If SEARCH_INDEX not configured, disable the search.
+try:
+    SOLR
+except NameError:
+    NO_SEARCH_INDEX = True
+else:
+    NO_SEARCH_INDEX = False
+
+

 try:
     SENTRY_DSN
 except NameError:
 try:
     SENTRY_DSN
 except NameError:


@@ -32,3 +48,11 @@ else:
         dsn=SENTRY_DSN,
         integrations=[DjangoIntegration()]
     )
         dsn=SENTRY_DSN,
         integrations=[DjangoIntegration()]
     )

+
+
+# Dummy secret key for development.
+try:
+    SECRET_KEY
+except NameError:
+    if DEBUG:
+        SECRET_KEY = 'not-a-secret-key'

diff --git a/src/wolnelektury/settings/basic.py b/src/wolnelektury/settings/basic.py
index 294ee45..b245ca5 100644 (file)
--- a/src/wolnelektury/settings/basic.py
+++ b/src/wolnelektury/settings/basic.py
@@ -5,7 +5,7 @@ from os import path
 from machina import MACHINA_MAIN_TEMPLATE_DIR
 from .paths import PROJECT_DIR
 
 from machina import MACHINA_MAIN_TEMPLATE_DIR
 from .paths import PROJECT_DIR
 

-DEBUG = False
+DEBUG = True

 MAINTENANCE_MODE = False
 
 ADMINS = [
 MAINTENANCE_MODE = False
 
 ADMINS = [


@@ -26,7 +26,6 @@ DATABASES = {
     }
 }
 
     }
 }
 

-SOLR = "http://localhost:8983/solr/wl/"

 SOLR_TEST = "http://localhost:8983/solr/wl_test/"
 SOLR_STOPWORDS = "/path/to/solr/data/conf/lang/stopwords_pl.txt"
 
 SOLR_TEST = "http://localhost:8983/solr/wl_test/"
 SOLR_STOPWORDS = "/path/to/solr/data/conf/lang/stopwords_pl.txt"
 

diff --git a/src/wolnelektury/settings/celery.py b/src/wolnelektury/settings/celery.py
index 0d9b778..a570b68 100644 (file)
--- a/src/wolnelektury/settings/celery.py
+++ b/src/wolnelektury/settings/celery.py
@@ -1,8 +1,6 @@
 # This file is part of Wolnelektury, licensed under GNU Affero GPLv3 or later.
 # Copyright © Fundacja Nowoczesna Polska. See NOTICE for more information.
 #
 # This file is part of Wolnelektury, licensed under GNU Affero GPLv3 or later.
 # Copyright © Fundacja Nowoczesna Polska. See NOTICE for more information.
 #

-CELERY_BROKER_URL = 'redis://'
-

 CELERY_TASK_EAGER_PROPAGATES = True
 CELERY_SEND_TASK_ERROR_EMAILS = True
 CELERY_ACCEPT_CONTENT = ['pickle']
 CELERY_TASK_EAGER_PROPAGATES = True
 CELERY_SEND_TASK_ERROR_EMAILS = True
 CELERY_ACCEPT_CONTENT = ['pickle']

diff --git a/src/wolnelektury/settings/custom.py b/src/wolnelektury/settings/custom.py
index 0ac8a8a..f3df7f3 100644 (file)
--- a/src/wolnelektury/settings/custom.py
+++ b/src/wolnelektury/settings/custom.py
@@ -7,7 +7,6 @@ from .paths import VAR_DIR
 # limit number of filtering tags
 MAX_TAG_LIST = 6
 
 # limit number of filtering tags
 MAX_TAG_LIST = 6
 

-NO_SEARCH_INDEX = False

 NO_CUSTOM_PDF = True
 
 CATALOGUE_DEFAULT_LANGUAGE = 'pol'
 NO_CUSTOM_PDF = True
 
 CATALOGUE_DEFAULT_LANGUAGE = 'pol'

diff --git a/src/wolnelektury/settings/static.py b/src/wolnelektury/settings/static.py
index f2a8423..f98d7ee 100644 (file)
--- a/src/wolnelektury/settings/static.py
+++ b/src/wolnelektury/settings/static.py
@@ -185,12 +185,7 @@ PIPELINE = {
     'CSS_COMPRESSOR': None,
     'JS_COMPRESSOR': 'pipeline.compressors.jsmin.JSMinCompressor',
     'COMPILERS': (
     'CSS_COMPRESSOR': None,
     'JS_COMPRESSOR': 'pipeline.compressors.jsmin.JSMinCompressor',
     'COMPILERS': (

-        'pipeline.compilers.sass.SASSCompiler',
-        # We could probably use PySCSS instead,
-        # but they have some serious problems, like:
-        # https://github.com/Kronuz/pyScss/issues/166 (empty list syntax)
-        # https://github.com/Kronuz/pyScss/issues/258 (bad @media order)
-        # 'pyscss_compiler.PySCSSCompiler',
+        'libsasscompiler.LibSassCompiler',

     )
 }
 
     )
 }