README.rst
1..
2 This file is part of citeproc-py-styles.
3 Copyright (C) 2016-2018 CERN.
4
5 citeproc-py-styles is free software; you can redistribute it and/or modify it
6 under the terms of the MIT License; see LICENSE file for more details.
7
8====================
9 citeproc-py-styles
10====================
11
12.. image:: https://github.com/inveniosoftware/citeproc-py-styles/workflows/CI/badge.svg
13 :target: https://github.com/inveniosoftware/citeproc-py-styles/actions?query=workflow%3ACI
14
15.. image:: https://img.shields.io/coveralls/inveniosoftware/citeproc-py-styles.svg
16 :target: https://coveralls.io/r/inveniosoftware/citeproc-py-styles
17
18.. image:: https://img.shields.io/pypi/v/citeproc-py-styles.svg
19 :target: https://pypi.org/pypi/citeproc-py-styles
20
21About
22=====
23
24This module is meant to be used as a static resources package, in order to make
25it easy to include the required Citation Style files (.csl) when using
26`citeproc-py <https://github.com/brechtm/citeproc-py>`_.
27
28In order to avoid always installing ~40MB of files each time you include it in
29a project you could specify it as an extra in your `setup.py`, and only use it
30in the production environment or as an optional feature of your module.
31(`Example setup.py <https://github.com/inveniosoftware/invenio-records-rest/blob/master/setup.py>`_)
32
33The included files are originally hosted on the `CSL Style Repository
34<https://github.com/citation-style-language/styles>`_ which belongs to the
35`CSL Project <http://citationstyles.org/>`_
36
37Note: The style files are referenced as a git submodule. This means that this
38repository/package is pinned on a specific commit of the CSL Style Repository,
39and thus may not include any fixes or new styles that may have been added.
40Next versions of this repository will of course 'bump' the styles version to
41the latest commit, but this will not happen on a scheduled basis for the time
42being.
43
44
45Installation
46============
47
48citeproc-py-styles is on PyPI so all you need is: ::
49
50 pip install citeproc-py-styles
51
52Usage
53=====
54
55This is a minimal example of how one could use `citeproc-py-styles` to render a
56citation with `citeproc-py`:
57
58.. code-block:: python
59
60 from citeproc import (Citation, CitationItem, CitationStylesBibliography,
61 CitationStylesStyle, formatter)
62 from citeproc.source.json import CiteProcJSON
63 from citeproc_styles import get_style_filepath
64
65 csl_data = json.loads("...")
66 source = CiteProcJSON(csl_data)
67
68 style_path = get_style_filepath('apa')
69 style = CitationStylesStyle(style_path)
70
71 bib = CitationStylesBibliography(style, source, formatter.plain)
72 bib.register(Citation([CitationItem('data_id')]))
73 print(''.join(bib.bibliography()[0]))
74
