~fabrixxm/lesanaweb

A read-only web interface to Lesana collections
switch to pyproject.toml, add 'datetime' filter
Add 'deploy' section to README
Update CHANGELOG

clone

read-only
https://git.sr.ht/~fabrixxm/lesanaweb
read/write
git@git.sr.ht:~fabrixxm/lesanaweb

You can also use your local clone with git send-email.

#Lesana Web

Read-only web interface to Lesana collections

#Requires

  • Lesana
  • Flask
  • Xapian python bindings from your package manager

#Config

Configuration is read from environment variables:

  • LW_COLLECTION_PATH : path to the collection folder. If not set, an error is raised.
  • LW_PAGE_SIZE : how many entries show per page in list. Defaults to 20.

#Deploy

Lesana Web is built on Flask framework and talks with webserver using WSGI protocol.

Details on how to setup WSGI depends on your webserver. Usually it needs a .wsgi file, wich is not distribuited with the code, and you need to write it.

If Lesana Web is in your PYTHONPATH , the .wsgi file is just:

from lesanaweb import app as application

Config environment variables should be set in your WSGI configuration.

Alternatively, python import path and/or environment variables can be set directly in the .wsgi file:

import sys, os

os.environ['LW_COLLECTION_PATH'] = "/path/to/lesana/collection"

sys.path.insert(0, '/path/where/lesanaweb/is/located')

from lesanaweb import app as application

#Templates

Lesana Web uses three templates, written using Jinja2 templating system:

  • index.html : show list of entries, used as homepage and for search results
  • entry.html : display entry details
  • about.html : display the about page
  • atom.xml : atom feed

The applications comes with basic templates, but it's possible to customize this templates creating that two file in templates/web directory under collection's base folder. Lesana Web will search that path first for templates, using included templates as fallback.

Template files in the templates/ directory are released under the Creative Commons Zero (CC0) license.

TODO : custom error templates

#Templates context

index.html template will get this vars in context:

  • q : search query string. Defined only in search route
  • page : current page number
  • entries : list of lesana.collection.Entry objects
  • settings : collection settings

entry.html template will get this vars in context:

  • entry : lesana.collection.Entry object
  • settings : collection settings

about.html template will get this vars in context:

  • readme: an html snippet with the rendered README contents
  • settings : collection settings

#Routes

Lesana Web defines four routes:

  • index : the default route. Loads index.html template. Gets querystring parameter:

    • p, the page number to show, starting from 1
  • search : loads index.html template. Gets querystring parameters:

    • p, the page number to show, starting from 1
    • q, the search query
  • entry : loads entry.html. It can return 404 if the requested entry does not exists, or 400 if the eid matches more than one entry. Gets url parameter:

    • eid, the entry's eid to show
  • about: loads about.html. Tries to load a README file from the root of the collection. In order it tries README.rst (interpreted as reStructuredText), README.md (interpreted as markdown) and README.txt or README, simply displayed as-is.

#Develop

git clone https://git.sr.ht/~fabrixxm/lesanaweb
  cd lesanaweb
  make env      # build a virtualenv
  make install  # install lesanaweb in venv in editable mode

  # if you have a collection
  LW_COLLECTION_PATH=/path/to/collection make run   # run flask
  # else
  mkdir -p work/collection
  make init
  make run