The recommended way of installing is using pip
:
pip install biblary
First, make sure the application is added to the INSTALLED_APPS
in your project settings:
# settings.py
INSTALLED_APPS = (
...
'biblary',
)
Next, add the URLs to your project:
# urls.py
from django.urls import path, include
urlpatterns = [
path('biblary/', include('biblary.urls', namespace='biblary')),
]
Finally, the adapter to the bibliography backend needs to be configured.
For example, to serve the contents of a file containing BibTeX entries, use the BibtexBibliography
adapter:
# settings.py
import pathlib
BIBLARY_BIBLIOGRAPHY_ADAPTER = 'biblary.bibliography.adapter.bibtex.BibtexBibliography'
BIBLARY_BIBLIOGRAPHY_ADAPTER_CONFIGURATION = {
'filepath': pathlib.Path('/some/path/to/bibliography.bib')
}
The filepath
is the only required key for the configuration and should be a pathlib.Path
object pointing to the BibTeX file.
This adapter is designed to serve the contents of a file containing BibTeX entries.
filepath
: apathlib.Path
object that points to the BibTeX file containing the bibliographic entries.
To provide an adapter to a custom bibliography backend, one should implement the biblary.bibliography.adapter.abstract.BibliographyAdapter
class:
# -*- coding: utf-8 -*-
import typing as t
from biblary.bibliography.adapter import BibliographyAdapter
from biblary.bibliography.entry import BibliographyEntry
class CustomBibliographyAdapter(BibliographyAdapter):
"""Implementation of a ``BibliographyAdapter``."""
def __init__(self, *args, **kwargs):
"""Construct a new instance and configure the adapter."""
super().__init__(*args, **kwargs)
def get_entries(self) -> t.List[BibliographyEntry]:
"""Return the list of bibliography entries."""
The constructor should define what keyword arguments it should take in order to configure the adapter.
The keyword arguments that are specified for the BIBLARY_BIBLIOGRAPHY_ADAPTER_CONFIGURATION
will be passed to the constructor of the adapter when the bibliography is loaded.
Finally, the get_entries
method should be implemented.
It should return a list of biblary.bibliography.entry.BiliographyEntry
instances, one for each entry in the bibliography.
This setting takes a tuple of regex patterns, for example
BIBLARY_BIBLIOGRAPHY_MAIN_AUTHOR_PATTERNS = ('Paul Dirac', r'.*Dirac')
The template tag main_author_class
will use this setting to determine if the author that it is passed is considered a main author.
If that is the case, the string defined by the BIBLARY_BIBLIOGRAPHY_MAIN_AUTHOR_CLASS
setting is returned.
This can be used in the index
template as follows:
{% for entry in entries %}
<div class="biblary-entry-authors">
{% for author in entry.author %}
<span class="biblary-entry-author {% main_author_class author %}">{{ author }}</span>
{% endfor %}
</div>
{% endfor %}
Any author that will match any of the patterns specified by the setting, will get the additional class.
Returned by the main_author_class
tag if the specified author matches any of the patterns defined by the BIBLARY_BIBLIOGRAPHY_MAIN_AUTHOR_PATTERNS
setting.
Default is biblary-entry-author-main
.