Merge pull request 'dev0.21' (#2) from dev0.21 into master

Reviewed-on: #2

README.md

@@ -1,3 +1,108 @@
 # lektor-citation
 
-An APA-style citation plugin for the lektor static content management system (https://getlektor.com).
+An APA-styled citation plugin for the lektor static content management system (https://getlektor.com).
+
+## Preparations
+
+Install the plugin by
+```
+lektor plugin add lektor-citation
+```
+
+or by copying this repository into the _packages_-folder of your lektor-project.
+
+Create an _citation.ini_ in its _configs_-folder:
+```
+[Bibtex]
+file = Literature.bib
+
+[default]
+priority = url
+link = /for-example/link-to-your/biblioprahy
+```
+
+And put a _Literature.bib_ BibTex-file into the project's _assets_-folder respectively.
+
+## Jinja_env
+
+### Bibliography
+To get a formated output of your whole BibTex library you can either
+1. Use method citation\_short\_output in the template of your literature page. It creates an unordered list of entries.
+```
+  <ul id="literatur">
+  {% for entry in citation_entries() %}
+  {{ citation_short_output(entry)|decode|safe }}
+  {% endfor %}
+
+</ul>
+```
+2. Use method citation\_full\_output instead. This creates a more complete html-output for every entry.
+```
+  {% for entry in citation_entries() %}
+  {{ citation_full_output(entry)|decode|safe }}
+  {% endfor %}
+```
+produces
+```
+<h2>{title}</h2><h3>{authors} ({pubYear})</h3>
+<p>{note}</p>
+<dl class="literature">
+<dt class="edition"></dt>
+<dd>{edition}</dd>
+<dt class="editors"></dt>
+<dd>{editors}</dd>
+<dt class="pages"></dt>
+<dd>{pages}</dd>
+<dt class="issbn"></dt>
+<dd>{issbn}</dd>
+<dt class="publisher"></dt>
+<dd>{publisher}</dd>
+</dl>
+```
+3. You may also use the citation\_entry method in combination with [pybtex*s __Entry__-class](https://docs.pybtex.org/api/parsing.html#pybtex.database.Entry). For example:
+
+```
+<ul>
+  {% for entry in citation_entries() %}
+<li>{{ citation_entry(entry).fields['title'] |decode }}</li>
+  {% endfor %}
+  </ul>
+```
+This creates an unordered list of all the titles of your bibtex file.
+Of course you can also use citation\_entry without a loop and put any id of your bibtex entries into it as parameter.
+
+Alternatively to the pybtex methods you can use the following **jinja_env globals**:
+
+    citation_authors_short(entry)
+    citation_authors_full(entry)
+    citation_editors_short(entry)
+    citation_editors_full(entry)
+    citation_pubYear(entry)
+    citation_edition(entry)
+    citation_publisher(entry)
+    citation_title(entry)
+    citation_url(entry)
+    citation_issbn(entry)
+    citation_pages(entry)
+    citation_note(entry)
+        
+### In-text Cites
+To cite a certain entry in your texts you can use the **jinja_env globals**:
+
+	citation_full_cite(id, link="")
+	citation_full_citeNP(id, link="")
+	
+Both methods create a complete hyperlink inside your text for the entry with _id_. You may give it any url to the _link_ parameter to e.g. link it to your bibliography page. The NP in the second stands for _No Parantheses_. So you'll receive e.g.
+
+	AuthorI & AuthorII (2019)
+or
+	
+	(AuthorI & AuthorII, 2019)
+
+#### link parameter
+Which url is used for your citation's link depends on what you set in the _citation.ini_ file. 
+* If you set _priority_ in the _default_ section to __url__ the link is set to the value of the _url_ field of the entry.
+* If there's no value in it the default-link you may set with _link_ in the same section is used.
+* If you set the _link_ parameter of the function it overwrites the former options.
+
+Thanks to the **lektor-jinja-content** plugin which is a dependency of this plugin you might also use the globals inside your markdown or html contents, too.

lektor_citation.py

@@ -0,0 +1,279 @@
+# -*- coding: utf-8 -*-
+import os
+from pylatexenc.latex2text import LatexNodes2Text
+from pybtex.database import parse_file
+from lektor.pluginsystem import Plugin
+
+
+class CitationPlugin(Plugin):
+    name = 'lektor-citation'
+    description = u'This Plugin should extend lektor with APA-styled citations using bibtex files. It was based on the known lektor-bibtex-support plugin by arunpersaud.'
+
+
+    def __init__(self, env, id):
+        super().__init__(env, id)
+
+        config = self.get_config()
+        self.bibfile = config.get('Bibtex.file', []).strip()
+        self.default_prio = config.get('default.priority', []).strip()
+        self.default_link = config.get('default.link', []).strip()
+
+        self.bib_data = parse_file(os.path.join(env.root_path, 'assets', self.bibfile))
+
+    def citation_entries(self):
+        return self.bib_data.entries
+
+    def citation_entry(self, id):
+        return self.bib_data.entries[id]
+    
+    def get_people_full(self, lAuthor):
+        authors = ""
+        n = 1
+        for author in lAuthor:
+            first =  author.first_names
+            if len(first) > 0 :
+                for item in first:
+                    authors += "{i} ".format(i = str(item))
+            middle =  author.middle_names
+            if len(middle) > 0 :
+                for item in middle:
+                    authors += "{i} ".format(i = str(item))
+            
+            prelast = author.prelast_names
+            if len(prelast) > 0:
+                for item in prelast:
+                    authors += "{i} ".format(i = str(item))
+            authors += str(author.last_names[0])
+            
+            if len(lAuthor) > 1:
+                
+                if n == (len(lAuthor) - 1):
+                    authors += " & "
+                elif n < (len(lAuthor) -1):
+                    authors += ", "
+
+            n = n + 1
+        return authors
+
+    
+
+    def get_people_short(self, lAuthor):
+        authors = ""
+        n = 1
+        for author in lAuthor:
+            prelast = author.prelast_names
+            if len(prelast) > 0:
+                for item in prelast:
+                    authors += "{i} ".format(i = str(item))
+            authors += str(author.last_names[0])
+            first =  author.first_names
+            if len(first) > 0 :
+                authors += ","
+                for item in first:
+                    authors += " {i}.".format(i = str(item[:1]))
+            middle =  author.middle_names
+            if len(middle) > 0 :
+                for item in middle:
+                    authors += " {i}.".format(i = str(item[:1]))
+            
+            if len(lAuthor) > 1:
+                
+                if n == (len(lAuthor) - 1):
+                    authors += " & "
+                elif n < (len(lAuthor) -1):
+                    authors += ", "
+
+            n = n + 1
+        return authors
+
+    def get_pubYear(self, e):
+        if "year" in e.fields.keys():
+            year = e.fields['year']
+        else:
+            year = ""
+        return year
+
+    def get_title(self, e):
+        if "title" in e.fields.keys():
+            title = e.fields['title']
+        else:
+            title = ""
+        return title
+
+    def get_edition(self, e):
+
+        if 'edition' in e.fields.keys():
+            edition = e.fields['edition']
+            edition = " ({ed}. Ed.)".format(ed = edition)
+        else:
+            edition = ""
+            
+        return edition
+
+    def get_publisher(self, e):
+        if 'publisher' in e.fields.keys():
+            publisher = e.fields['publisher']
+            if 'address' in e.fields.keys():
+                location = e.fields['address']
+                publisher = " {location}: {publisher}.".format(location = location, publisher = publisher)
+            elif publisher:
+                publisher = " {publisher}.".format(publisher = publisher)
+            else:
+                publisher = ""
+        return publisher
+
+    def get_pages(self, e):
+
+        if 'pages' in e.fields.keys():
+            pages = e.fields['pages']
+        else:
+            pages = ""
+        return pages
+
+    def get_issbn(self, e):
+        if 'issbn' in e.fields.keys():
+            issbn = e.fields['issbn']
+        else:
+            issbn = ""
+        return issbn
+
+    def get_note(self, e):
+        if 'note' in e.fields.keys():
+            note = e.fields['note']
+        else:
+            note = ""
+        return note
+
+    def get_url(self, e):
+        if "url" in e.fields.keys() and len(e.fields['url']) > 0:
+            link = e.fields['url']
+        else:
+            link = "?"
+        return link
+    
+
+    def get_editors_short(self, e):
+        if "editor" in e.persons.keys():
+            editors = self.get_people_short(e.persons['editor'])
+        else:
+            editors = ""
+        return editors
+    
+    def get_editors_full(self, e):
+        if "editor" in e.persons.keys():
+            editors = self.get_people_full(e.persons['editor'])
+        else:
+            editors = ""
+        return editors
+
+    def get_authors_short(self, e):
+        if "author" in e.persons.keys():
+            authors = self.get_people_short(e.persons['author'])
+        else:
+            authors = ""
+        return authors
+
+    def get_authors_full(self, e):
+        if "author" in e.persons.keys():
+            authors = self.get_people_full(e.persons['author'])
+        else:
+            authors = ""
+        return authors
+    
+        
+
+            
+    def citation_short_output(self, id, link=None):
+        e = self.citation_entry(id)
+        link = self.get_url(e)
+        authors = self.get_authors_short(e)
+        title = self.get_title(e)    
+        year = self.get_pubYear(e)
+        edition = self.get_edition(e)
+        publisher = self.get_publisher(e) 
+            
+        output = '<li id="{eid}"><a href="{link}" class="litref">{authors} ({pubYear}).</a> <em>{title}</em>{edition}. {publisher}'.format(eid = id, link = link, authors = authors, pubYear = year, title = title, edition = edition, publisher = publisher)
+        return output
+        
+    def citation_full_output(self, id):
+        e = self.citation_entry(id)
+        link = self.get_url(e)
+        authors = self.get_authors_full(e)
+        editors = self.get_editors_full(e)        
+        title = self.get_title(e)
+        year = self.get_pubYear(e)
+        edition = self.get_edition(e)
+        pages = self.get_pages(e)
+        issbn = self.get_issbn(e)    
+        note = self.get_note(e)
+        publisher = self.get_publisher(e)
+
+        output = """<h2>{title}</h2><h3>{authors} ({pubYear})</h3>
+<p>{note}</p>
+<dl class="literature">
+<dt class="edition"></dt>
+<dd>{edition}</dd>
+<dt class="editors"></dt>
+<dd>{editors}</dd>
+<dt class="pages"></dt>
+<dd>{pages}</dd>
+<dt class="issbn"></dt>
+<dd>{issbn}</dd>
+<dt class="publisher"></dt>
+<dd>{publisher}</dd>
+</dl>
+""".format(eid = id, link = link, authors = authors, pubYear = year, title = title, edition = edition, publisher = publisher, editors = editors, pages = pages, issbn = issbn, note = note)
+        return output
+
+    def citation_base_cite(self,id,link="",output=""):
+        e = self.citation_entry(id)
+
+        if len(link) > 1:
+            link = link
+        elif self.default_prio == "url":
+            link = self.get_url(e)
+            if len(link) < 2:
+                link = self.default_link
+        else:
+            link = self.default_link
+
+        authors = self.get_authors_short(e)
+        year = self.get_pubYear(e)
+        output = output.format(link = link, id = id, authors = authors, pubYear = year)
+        return output
+
+    def citation_full_cite(self,id,link=""):
+        output = self.citation_base_cite(id,link="",output="""<a href=\"{link}#{id}\" class=\"litref\">({authors}, {pubYear})</a>""")
+        return output
+
+    def citation_full_citeNP(self,id,link=""):
+        output = self.citation_base_cite(id,link="",output="""<a href=\"{link}#{id}\" class=\"litref\">{authors} ({pubYear})</a>""")
+        return output
+
+    def on_setup_env(self, **extra):
+        def decode_filter(value):
+            """ Make sure that special chars like german umlaute or accents are displayed in unicode """
+            return LatexNodes2Text().latex_to_text(value.replace(" & ", " \& "))
+     
+        self.env.jinja_env.globals['citation_entries'] = self.citation_entries
+        self.env.jinja_env.globals['citation_entry'] = self.citation_entry
+        self.env.jinja_env.globals['citation_short_output'] = self.citation_short_output
+        self.env.jinja_env.globals['citation_full_output'] = self.citation_full_output
+        self.env.jinja_env.globals['citation_full_cite'] = self.citation_full_cite
+        self.env.jinja_env.globals['citation_full_citeNP'] = self.citation_full_citeNP
+        self.env.jinja_env.globals['citation_authors_short'] = self.get_authors_short
+        self.env.jinja_env.globals['citation_authors_full'] = self.get_authors_full
+        self.env.jinja_env.globals['citation_editors_short'] = self.get_editors_short
+        self.env.jinja_env.globals['citation_editors_full'] = self.get_editors_full        
+        self.env.jinja_env.globals['citation_pubYear'] = self.get_pubYear
+        self.env.jinja_env.globals['citation_edition'] = self.get_edition
+        self.env.jinja_env.globals['citation_publisher'] = self.get_publisher        
+        self.env.jinja_env.globals['citation_title'] = self.get_title
+        self.env.jinja_env.globals['citation_url'] = self.get_url
+        self.env.jinja_env.globals['citation_issbn'] = self.get_issbn
+        self.env.jinja_env.globals['citation_pages'] = self.get_pages
+        self.env.jinja_env.globals['citation_note'] = self.get_note
+        self.env.jinja_env.filters['decode'] = decode_filter
+        
+        
+           

setup.cfg

@@ -0,0 +1,2 @@
+[bdist_wheel]
+universal=1

setup.py

@@ -0,0 +1,39 @@
+import ast
+import io
+import re
+
+from setuptools import setup, find_packages
+
+with io.open('README.md', 'rt', encoding="utf8") as f:
+    readme = f.read()
+
+_description_re = re.compile(r'description\s+=\s+(?P<description>.*)')
+
+with open('lektor_citation.py', 'rb') as f:
+    description = str(ast.literal_eval(_description_re.search(
+        f.read().decode('utf-8')).group(1)))
+
+setup(
+    author='Homer S',
+    author_email='homer77@ismus.net',
+    description=description,
+    keywords='Lektor plugin',
+    license='MIT',
+    long_description=readme,
+    long_description_content_type='text/markdown',
+    name='lektor-citation',
+    packages=find_packages(),
+    py_modules=['lektor_citation'],
+    url='https://git.ismus.net/homer77/lektor-citation',
+    version='0.1',
+    classifiers=[
+        'Framework :: Lektor',
+        'Environment :: Plugins',
+    ],
+    entry_points={
+        'lektor.plugins': [
+            'citation = lektor_citation:CitationPlugin',
+        ]
+    },
+    install_requires=['pybtex','pylatexenc','lektor-jinja-content']
+)