From: Radek Czajka Date: Thu, 29 Aug 2019 08:11:08 +0000 (+0200) Subject: Start updating docs. X-Git-Url: https://git.mdrn.pl/wolnelektury.git/commitdiff_plain/f8237807eed38189cf909c73d37c2b3d1e2d584a?ds=sidebyside 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 13c0ed2b8..139cccc00 100644 --- 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 ------- @@ -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 . + Dependencies ============ - * Python 3.4+ + * Python 3.5-3.7 * All packages listed in requirements.txt - * Sass>=3.2 + 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). + Bundled software ================ @@ -79,7 +92,6 @@ Bundled software with relevant attribution and licensing - Authors ======= * Marek Stępniowski diff --git a/doc/advanced-setup.rst b/doc/advanced-setup.rst new file mode 100644 index 000000000..97a82c224 --- /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 `. + + +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 index 000000000..f232aa6e1 --- /dev/null +++ b/doc/basic-setup.rst @@ -0,0 +1,53 @@ +=========== +Basic setup +=========== + +Wolne Lektury is a `Django `_ project. + +If you're new to Django, we strongly recommend you complete +the `Django Girls Tutorial `_ and/or +the official :django:`Django Tutorial ` +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 1e8ba2890..7c09286af 100644 --- 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. -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'] @@ -222,6 +222,9 @@ man_pages = [ ['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 index 000000000..fc4514fd3 --- /dev/null +++ b/doc/deployment.rst @@ -0,0 +1,4 @@ +========== +Deployment +========== + diff --git a/doc/index.rst b/doc/index.rst index 0c2d1fdfe..9018fb063 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -9,7 +9,9 @@ Welcome to Wolne Lektury's documentation! .. toctree:: :maxdepth: 2 - installation + basic-setup + advanced-setup + deployment architecture reference diff --git a/doc/installation.rst b/doc/installation.rst deleted file mode 100644 index 81ef4def7..000000000 --- a/doc/installation.rst +++ /dev/null @@ -1,54 +0,0 @@ -===== -Setup -===== - -Requirements ------------- - -* `Python 3.5-3.7 `_ -* Python requiremets: ``pip install -r requirements/requirements.txt`` -* a library for your database of choice - (see `DBs supported by Django `_) -* `Sass `_ >= 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 `_ 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 b3fc758d6..ce0b5e912 100644 --- 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 +libsasscompiler==0.1.5 jsmin fnp-django-pagination==2.2.3 @@ -50,9 +51,6 @@ librarian==1.7.4 # celery tasks celery[redis]==4.3.0 -# spell checking -pyenchant - # OAI-PMH pyoai==2.5.0 diff --git a/src/catalogue/models/book.py b/src/catalogue/models/book.py index 9116a4657..5dbda4770 100644 --- 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): + """ + >>> 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 diff --git a/src/catalogue/tests/test_doctests.py b/src/catalogue/tests/test_doctests.py new file mode 100644 index 000000000..0225e59aa --- /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 8e0815b3f..f8451cc23 100644 --- a/src/wolnelektury/settings/__init__.py +++ b/src/wolnelektury/settings/__init__.py @@ -23,6 +23,22 @@ except ImportError: 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: @@ -32,3 +48,11 @@ else: 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 294ee45f0..b245ca5fa 100644 --- 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 -DEBUG = False +DEBUG = True 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" diff --git a/src/wolnelektury/settings/celery.py b/src/wolnelektury/settings/celery.py index 0d9b7785a..a570b688c 100644 --- 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. # -CELERY_BROKER_URL = 'redis://' - 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 0ac8a8a77..f3df7f3ee 100644 --- 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 -NO_SEARCH_INDEX = False NO_CUSTOM_PDF = True CATALOGUE_DEFAULT_LANGUAGE = 'pol' diff --git a/src/wolnelektury/settings/static.py b/src/wolnelektury/settings/static.py index f2a8423bb..f98d7ee1a 100644 --- 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': ( - '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', ) }