| Name | pelican-pybtex JSON |
| Version |
1.0.0b1
JSON |
| download |
| home_page | None |
| Summary | Manage your academic publications page with Pelican and pybtex (BibTeX) |
| upload_time | 2024-11-06 17:26:40 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4.0,>=3.9 |
| license | None |
| keywords |
bibtex
pelican
plugin
pybtex
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<!--
SPDX-FileCopyrightText: Copyright © 2024 André Anjos <andre.dos.anjos@gmail.com>
SPDX-License-Identifier: MIT
-->
[](https://github.com/anjos/pelican-pybtex/actions)
[](https://htmlpreview.github.io/?https://github.com/anjos/pelican-pybtex/blob/python-coverage-comment-action-data/htmlcov/index.html)
[](https://pypi.org/project/pelican-pybtex/)
[](https://pypi.org/project/pelican-pybtex/)
# pybtex: A Plugin for Pelican
Organize your scientific publications with [pybtex](https://pybtex.org)
([BibTeX](https://www.bibtex.com/g/bibtex-format/)) in [Pelican](https://getpelican.com).
## Installation
This plugin can be installed via:
```sh
pip install pelican-pybtex
````
This a "namespace plugin" for Pelican. After installation, it should be automatically
detected. It is enabled by default if `PLUGINS` is not set on your configuration. In
case that variable is set, add `pybtex` to the list of plugins to load. For more
information, check [How to Use
Plugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins)
documentation.
## Usage
This plugin reads a user-specified [pybtex supported
file](https://docs.pybtex.org/formats.html#bibliography-formats) and populates the
global Jinja2 context used by Pelican with a `publications` variable. The `publications`
variable is a list of dictionaries itself, each containing the following fields,
corresponding to individual entries in the provided compatible files:
* `label`: The formatted label (depends on the used style, but usually something like
`3`, `Ein05`, or `Einstein, 1905`).
* `key`: The pybtex (BibTeX) database key
* `year`: The year of the entry
* `html`: An HTML-formatted version of the entry
* `bibtex`: A BibTeX-formatted version of the entry, wrapped in a [pygments
HTML-formatted](https://pygments.org/docs/quickstart/) version. The pygments output
respects the settings for `PYGMENTS_RST_OPTIONS` in Pelican.
Use the following Pelican configuration key to list sources to be parsed and populate
the `publications` context:
```python
# any pybtex supported input format is accepted
PYBTEX_SOURCES = ["content/publications.bib"]
```
If files indicated on that list are present and readable, they will be loaded. Errors are
reported, but ignored during generation. Check Pelican logs for details while building
your site.
Note that relative paths are considered with respect to the location of the setting of
`PATH` in `pelicanconf.py` (typically the `content` directory). If `PATH` itself is
relative, it is considered relative to the location of `pelicanconf.py` itself.
### Extra fields
If you also set `PYBTEX_ADD_ENTRY_FIELDS`, then if any other field listed in this
setting will also be included *verbatim* in the dictionary of each entry. This feature
can be used, e.g., to include more URLs in a work, and then display those using a
custom template as explained later.
```python
PYBTEX_ADD_ENTRY_FIELDS = ["url", "pdf", "slides", "poster"]
```
### Formatting style
By default, `PYBTEX_FORMAT_STYLE` is set to `plain`. You may further customize this
setting to one of the biobliography formatting styles supported by pybtex (currently
"plain", "alpha", "unsrt", and "unsrtalpha"). You may check the formatting style of
these BibTeX styles [on this
reference](https://www.overleaf.com/learn/latex/Bibtex_bibliography_styles). We
currently do not support custom bibliographic styles. Create an issue if you would like
to work on this.
### Publications page
This plugin provides a [default
`publications.html`](src/pelican/plugins/pybtex/templates/publications.html) template
that will render all publications *correctly loaded* from `PYBTEX_SOURCES`, ordered by
year, in reverse chronological order, and without BibTeX-style labels. Note that, if
there are no valid entries on `PYBTEX_SOURCES`, then a `publications.html` page is not
generated.
You may also want to override the default template, or parts of it with your own
modifications. To do so, create your own `publications.html` template, then use
`THEME_TEMPLATES_OVERRIDES` and `THEME_STATIC_PATHS` to add search paths for template
resolution. For example, to add a short introductory text, we could override the
`before_content` block on the default template like so:
1. Create a file called `templates/publications.html` on your site sources, with the
following (example) contents:
```html
{% extends "!pybtex/publications.html" %}
{% block before_content %}
<p id="before-para">This will appear before the publication lists. One could use this
to display their h-index, provide links to Google Scholar or ORCid.</p>
{% endblock %}
<!-- set PYBTEX_ADD_ENTRY_FIELDS = ["url", "pdf", "slides", "poster"] -->
<!-- then, use it in your template override like so: -->
{% block content_pybtex %}
<div id="pybtex">
{% for item in publications %}
<details id="{{ item.key }}">
<summary>[{{ item.label }}] {{ item.html }}</summary>
<ul>
{% for k in ("url", "pdf", "slides", "poster") %}
{% if k in item %}<li>{{ k }}: {{ item[k] }}</li>{% endif %}
{% endfor %}
</ul>
</details>
{% endfor %}
</div>
{% endblock %}
```
2. Optionally, create a directory called `static` in which you may pour static files
that control the look of your inserted content.
3. In `pelicanconf.py`, set:
```python
THEME_TEMPLATES_OVERRIDES = ["templates"]
# STATIC_PATHS = ["static"] ## if you also have static files to be copied
# PUBLICATIONS_SAVE_AS = "publications/index.html" ## to change the default output file
# PUBLICATIONS_URL = "publications/" ## to change the default URL for publications
```
### Local bibliography in articles and pages
You may use markers such as `[@bibkey]` or `[@@bibkey]` on your articles and pages in
restructuredtext or markdown formats, to refer to bibliography entries from the
`PYBTEX_SOURCES`. This process is similar to using BibTeX database entries in your
LaTeX sources by using the `\cite{bibkey}` command. In this case, this plugin will
replace these citations with links to a bibliography database *injected* at the end of
the article or post.
The global `PYBTEX_FORMAT_STYLE` is respected while formatting bibliographies. You may
override the style for the current article or page using the metadata entry
`pybtex_format_style`. The same mechanism is available for `PYBTEX_ADD_ENTRY_FIELDS`,
which can be locally overriden by `pybtex_add_entry_fields` metadata entry.
You may also add further enrich article or page metadata defining a specific
`pybtex_sources`. In such a case, these files will be loaded respecting the same rules
as for `PYBTEX_SOURCES`. Specifically, relative paths are first searched at the location
of the article or page, and then default on using the `PATH` setting in
`pelicanconf.py`. Article and page bibliography markers will then be resolved by first
looking at entries in the local `pybtex_sources`, and then on the global
`PYBTEX_SOURCES` entry in `pelicanconf.py`.
Be aware that in case repeated citation keys are found across all bibliography
databases, **the last occurence is used** while resolving local bibliography for
articles an pages.
Finally, local bibliography formatting is controlled by the [default
`bibliography.html`](src/pelican/plugins/pybtex/templates/bibliography.html) template
that is shipped with this package. This templates defines the contents of the
*injected* bibliography section on articles and pages. You may override this template in
a similar way to what was explained above for the global `publications.html` template,
by setting the `THEME_TEMPLATES_OVERRIDES` Pelican variable.
## Contributing
Contributions are welcome and appreciated. Every little bit helps. You can
contribute by improving the documentation, adding missing features, and fixing bugs. You
can also help out by reviewing and commenting on [existing
issues](https://github.com/anjos/pelican-pybtex/issues).
To start contributing to this plugin, review the [Contributing to
Pelican](https://docs.getpelican.com/en/latest/contribute.html) documentation, beginning
with the **Contributing Code** section.
## License
This project was inspired by the [original BibTeX
plugin](https://github.com/vene/pelican-bibtex), developed by Vlad Niculae, and
[pelican-cite plugin](https://github.com/VorpalBlade/pelican-cite), by Arvid Norlander.
This project and further modifications are licensed under the MIT license.
Raw data
{
"_id": null,
"home_page": null,
"name": "pelican-pybtex",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.9",
"maintainer_email": null,
"keywords": "bibtex, pelican, plugin, pybtex",
"author": null,
"author_email": "Andre Anjos <andre.dos.anjos@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/44/f5/fc4c47deb5617853e7a5348210c50847015de33ccc1182490349ea39d7e8/pelican_pybtex-1.0.0b1.tar.gz",
"platform": null,
"description": "<!--\nSPDX-FileCopyrightText: Copyright \u00a9 2024 Andr\u00e9 Anjos <andre.dos.anjos@gmail.com>\nSPDX-License-Identifier: MIT\n-->\n\n[](https://github.com/anjos/pelican-pybtex/actions)\n[](https://htmlpreview.github.io/?https://github.com/anjos/pelican-pybtex/blob/python-coverage-comment-action-data/htmlcov/index.html)\n[](https://pypi.org/project/pelican-pybtex/)\n[](https://pypi.org/project/pelican-pybtex/)\n\n\n# pybtex: A Plugin for Pelican\n\nOrganize your scientific publications with [pybtex](https://pybtex.org)\n([BibTeX](https://www.bibtex.com/g/bibtex-format/)) in [Pelican](https://getpelican.com).\n\n## Installation\n\nThis plugin can be installed via:\n\n```sh\npip install pelican-pybtex\n````\n\nThis a \"namespace plugin\" for Pelican. After installation, it should be automatically\ndetected. It is enabled by default if `PLUGINS` is not set on your configuration. In\ncase that variable is set, add `pybtex` to the list of plugins to load. For more\ninformation, check [How to Use\nPlugins](https://docs.getpelican.com/en/latest/plugins.html#how-to-use-plugins)\ndocumentation.\n\n## Usage\n\nThis plugin reads a user-specified [pybtex supported\nfile](https://docs.pybtex.org/formats.html#bibliography-formats) and populates the\nglobal Jinja2 context used by Pelican with a `publications` variable. The `publications`\nvariable is a list of dictionaries itself, each containing the following fields,\ncorresponding to individual entries in the provided compatible files:\n\n* `label`: The formatted label (depends on the used style, but usually something like\n`3`, `Ein05`, or `Einstein, 1905`).\n* `key`: The pybtex (BibTeX) database key\n* `year`: The year of the entry\n* `html`: An HTML-formatted version of the entry\n* `bibtex`: A BibTeX-formatted version of the entry, wrapped in a [pygments\nHTML-formatted](https://pygments.org/docs/quickstart/) version. The pygments output\nrespects the settings for `PYGMENTS_RST_OPTIONS` in Pelican.\n\nUse the following Pelican configuration key to list sources to be parsed and populate\nthe `publications` context:\n\n```python\n# any pybtex supported input format is accepted\nPYBTEX_SOURCES = [\"content/publications.bib\"]\n```\n\nIf files indicated on that list are present and readable, they will be loaded. Errors are\nreported, but ignored during generation. Check Pelican logs for details while building\nyour site.\n\nNote that relative paths are considered with respect to the location of the setting of\n`PATH` in `pelicanconf.py` (typically the `content` directory). If `PATH` itself is\nrelative, it is considered relative to the location of `pelicanconf.py` itself.\n\n### Extra fields\n\nIf you also set `PYBTEX_ADD_ENTRY_FIELDS`, then if any other field listed in this\nsetting will also be included *verbatim* in the dictionary of each entry. This feature\ncan be used, e.g., to include more URLs in a work, and then display those using a\ncustom template as explained later.\n\n```python\nPYBTEX_ADD_ENTRY_FIELDS = [\"url\", \"pdf\", \"slides\", \"poster\"]\n```\n\n### Formatting style\n\nBy default, `PYBTEX_FORMAT_STYLE` is set to `plain`. You may further customize this\nsetting to one of the biobliography formatting styles supported by pybtex (currently\n\"plain\", \"alpha\", \"unsrt\", and \"unsrtalpha\"). You may check the formatting style of\nthese BibTeX styles [on this\nreference](https://www.overleaf.com/learn/latex/Bibtex_bibliography_styles). We\ncurrently do not support custom bibliographic styles. Create an issue if you would like\nto work on this.\n\n### Publications page\n\nThis plugin provides a [default\n`publications.html`](src/pelican/plugins/pybtex/templates/publications.html) template\nthat will render all publications *correctly loaded* from `PYBTEX_SOURCES`, ordered by\nyear, in reverse chronological order, and without BibTeX-style labels. Note that, if\nthere are no valid entries on `PYBTEX_SOURCES`, then a `publications.html` page is not\ngenerated.\n\nYou may also want to override the default template, or parts of it with your own\nmodifications. To do so, create your own `publications.html` template, then use\n`THEME_TEMPLATES_OVERRIDES` and `THEME_STATIC_PATHS` to add search paths for template\nresolution. For example, to add a short introductory text, we could override the\n`before_content` block on the default template like so:\n\n1. Create a file called `templates/publications.html` on your site sources, with the\n following (example) contents:\n\n ```html\n {% extends \"!pybtex/publications.html\" %}\n\n {% block before_content %}\n <p id=\"before-para\">This will appear before the publication lists. One could use this\n to display their h-index, provide links to Google Scholar or ORCid.</p>\n {% endblock %}\n\n <!-- set PYBTEX_ADD_ENTRY_FIELDS = [\"url\", \"pdf\", \"slides\", \"poster\"] -->\n <!-- then, use it in your template override like so: -->\n {% block content_pybtex %}\n <div id=\"pybtex\">\n {% for item in publications %}\n <details id=\"{{ item.key }}\">\n <summary>[{{ item.label }}] {{ item.html }}</summary>\n <ul>\n {% for k in (\"url\", \"pdf\", \"slides\", \"poster\") %}\n {% if k in item %}<li>{{ k }}: {{ item[k] }}</li>{% endif %}\n {% endfor %}\n </ul>\n </details>\n {% endfor %}\n </div>\n {% endblock %}\n ```\n\n2. Optionally, create a directory called `static` in which you may pour static files\n that control the look of your inserted content.\n3. In `pelicanconf.py`, set:\n\n ```python\n THEME_TEMPLATES_OVERRIDES = [\"templates\"]\n # STATIC_PATHS = [\"static\"] ## if you also have static files to be copied\n # PUBLICATIONS_SAVE_AS = \"publications/index.html\" ## to change the default output file\n # PUBLICATIONS_URL = \"publications/\" ## to change the default URL for publications\n ```\n\n### Local bibliography in articles and pages\n\nYou may use markers such as `[@bibkey]` or `[@@bibkey]` on your articles and pages in\nrestructuredtext or markdown formats, to refer to bibliography entries from the\n`PYBTEX_SOURCES`. This process is similar to using BibTeX database entries in your\nLaTeX sources by using the `\\cite{bibkey}` command. In this case, this plugin will\nreplace these citations with links to a bibliography database *injected* at the end of\nthe article or post.\n\nThe global `PYBTEX_FORMAT_STYLE` is respected while formatting bibliographies. You may\noverride the style for the current article or page using the metadata entry\n`pybtex_format_style`. The same mechanism is available for `PYBTEX_ADD_ENTRY_FIELDS`,\nwhich can be locally overriden by `pybtex_add_entry_fields` metadata entry.\n\nYou may also add further enrich article or page metadata defining a specific\n`pybtex_sources`. In such a case, these files will be loaded respecting the same rules\nas for `PYBTEX_SOURCES`. Specifically, relative paths are first searched at the location\nof the article or page, and then default on using the `PATH` setting in\n`pelicanconf.py`. Article and page bibliography markers will then be resolved by first\nlooking at entries in the local `pybtex_sources`, and then on the global\n`PYBTEX_SOURCES` entry in `pelicanconf.py`.\n\nBe aware that in case repeated citation keys are found across all bibliography\ndatabases, **the last occurence is used** while resolving local bibliography for\narticles an pages.\n\nFinally, local bibliography formatting is controlled by the [default\n`bibliography.html`](src/pelican/plugins/pybtex/templates/bibliography.html) template\nthat is shipped with this package. This templates defines the contents of the\n*injected* bibliography section on articles and pages. You may override this template in\na similar way to what was explained above for the global `publications.html` template,\nby setting the `THEME_TEMPLATES_OVERRIDES` Pelican variable.\n\n## Contributing\n\nContributions are welcome and appreciated. Every little bit helps. You can\ncontribute by improving the documentation, adding missing features, and fixing bugs. You\ncan also help out by reviewing and commenting on [existing\nissues](https://github.com/anjos/pelican-pybtex/issues).\n\nTo start contributing to this plugin, review the [Contributing to\nPelican](https://docs.getpelican.com/en/latest/contribute.html) documentation, beginning\nwith the **Contributing Code** section.\n\n## License\n\nThis project was inspired by the [original BibTeX\nplugin](https://github.com/vene/pelican-bibtex), developed by Vlad Niculae, and\n[pelican-cite plugin](https://github.com/VorpalBlade/pelican-cite), by Arvid Norlander.\nThis project and further modifications are licensed under the MIT license.\n",
"bugtrack_url": null,
"license": null,
"summary": "Manage your academic publications page with Pelican and pybtex (BibTeX)",
"version": "1.0.0b1",
"project_urls": {
"Homepage": "https://github.com/anjos/pelican-pybtex",
"Issue Tracker": "https://github.com/anjos/pelican-pybtex/issues"
},
"split_keywords": [
"bibtex",
" pelican",
" plugin",
" pybtex"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "b5adc207861821ad67f74f492e2d45fb4a8918593c502375060142aaac3a2d39",
"md5": "86f419e0a679f6c576753d9596beeda2",
"sha256": "009db13906af4b91df557af8b60f76db601972632084bc638aae5f6a23880872"
},
"downloads": -1,
"filename": "pelican_pybtex-1.0.0b1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "86f419e0a679f6c576753d9596beeda2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.9",
"size": 14904,
"upload_time": "2024-11-06T17:26:38",
"upload_time_iso_8601": "2024-11-06T17:26:38.913838Z",
"url": "https://files.pythonhosted.org/packages/b5/ad/c207861821ad67f74f492e2d45fb4a8918593c502375060142aaac3a2d39/pelican_pybtex-1.0.0b1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "44f5fc4c47deb5617853e7a5348210c50847015de33ccc1182490349ea39d7e8",
"md5": "f9f40b0a912677db29d961b0d05b6526",
"sha256": "06b0c076dca22932da0188c02d16c76a9e5a1679c396912cf38db1287cdf5cac"
},
"downloads": -1,
"filename": "pelican_pybtex-1.0.0b1.tar.gz",
"has_sig": false,
"md5_digest": "f9f40b0a912677db29d961b0d05b6526",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.9",
"size": 13632,
"upload_time": "2024-11-06T17:26:40",
"upload_time_iso_8601": "2024-11-06T17:26:40.669801Z",
"url": "https://files.pythonhosted.org/packages/44/f5/fc4c47deb5617853e7a5348210c50847015de33ccc1182490349ea39d7e8/pelican_pybtex-1.0.0b1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 17:26:40",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anjos",
"github_project": "pelican-pybtex",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pelican-pybtex"
}
