Source code for sphinxcontrib.bibtex.directives

    New Doctree Directives

    .. autoclass:: BibliographyDirective

        .. automethod:: run
        .. automethod:: process_bibfile
        .. automethod:: update_bibfile_cache
        .. automethod:: parse_bibfile

    .. autofunction:: process_start_option

import ast  # parse(), used for filter
import os.path  # getmtime()

from docutils.parsers.rst import Directive, directives
from sphinx.util.console import bold, standout

from pybtex.database.input import bibtex
from pybtex.database import BibliographyData

from sphinxcontrib.bibtex.cache import BibliographyCache, BibfileCache
from sphinxcontrib.bibtex.nodes import bibliography

[docs]def process_start_option(value): """Process and validate the start option value of a :rst:dir:`bibliography` directive. If *value* is ``continue`` then this function returns -1, otherwise *value* is converted into a positive integer. """ if value == "continue": return -1 else: return directives.positive_int(value)
[docs]class BibliographyDirective(Directive): """Class for processing the :rst:dir:`bibliography` directive. Parses the bibliography files, and produces a :class:`~sphinxcontrib.bibtex.nodes.bibliography` node. .. seealso:: Further processing of the resulting :class:`~sphinxcontrib.bibtex.nodes.bibliography` node is done by :class:`~sphinxcontrib.bibtex.transforms.BibliographyTransform`. """ required_arguments = 1 optional_arguments = 0 final_argument_whitespace = True has_content = False option_spec = { 'cited': directives.flag, 'notcited': directives.flag, 'all': directives.flag, 'filter': directives.unchanged, 'style': directives.unchanged, 'list': directives.unchanged, 'enumtype': directives.unchanged, 'start': process_start_option, 'encoding': directives.encoding, 'labelprefix': directives.unchanged, 'keyprefix': directives.unchanged, }
[docs] def run(self): """Process .bib files, set file dependencies, and create a node that is to be transformed to the entries of the bibliography. """ env = self.state.document.settings.env # create id and cache for this node # this id will be stored with the node # and is used to look up additional data in env.bibtex_cache # (implementation note: new_serialno only guarantees unique # ids within a single document, but we need the id to be # unique across all documents, so we also include the docname # in the id) id_ = 'bibtex-bibliography-%s-%s' % ( env.docname, env.new_serialno('bibtex')) if "filter" in self.options: if "all" in self.options:":filter: overrides :all:")) if "notcited" in self.options:":filter: overrides :notcited:")) if "cited" in self.options:":filter: overrides :cited:")) try: filter_ = ast.parse(self.options["filter"]) except SyntaxError: standout("syntax error in :filter: expression") + " (" + self.options["filter"] + "); " "the option will be ignored" ) filter_ = ast.parse("cited") elif "all" in self.options: filter_ = ast.parse("True") elif "notcited" in self.options: filter_ = ast.parse("not cited") else: # the default filter: include only cited entries filter_ = ast.parse("cited") bibcache = BibliographyCache( list_=self.options.get("list", "citation"), enumtype=self.options.get("enumtype", "arabic"), start=self.options.get("start", 1), style=self.options.get( "style",, filter_=filter_, encoding=self.options.get( 'encoding', self.state.document.settings.input_encoding), labelprefix=self.options.get("labelprefix", ""), keyprefix=self.options.get("keyprefix", ""), labels={}, bibfiles=[], ) if (bibcache.list_ not in set(["bullet", "enumerated", "citation"])): "unknown bibliography list type '{0}'.".format(bibcache.list_)) for bibfile in self.arguments[0].split(): # convert to normalized absolute path to ensure that the same file # only occurs once in the cache bibfile = os.path.normpath(env.relfn2path(bibfile.strip())[1]) self.process_bibfile(bibfile, bibcache.encoding) env.note_dependency(bibfile) bibcache.bibfiles.append(bibfile) env.bibtex_cache.set_bibliography_cache(env.docname, id_, bibcache) return [bibliography('', ids=[id_])]
[docs] def parse_bibfile(self, bibfile, encoding): """Parse *bibfile*, and return parsed data. :param bibfile: The bib file name. :type bibfile: ``str`` :return: The parsed bibliography data. :rtype: :class:`pybtex.database.BibliographyData` """ app = parser = bibtex.Parser(encoding) bold("parsing bibtex file {0}... ".format(bibfile)), nonl=True) parser.parse_file(bibfile)"parsed {0} entries" .format(len( return
[docs] def update_bibfile_cache(self, bibfile, mtime, encoding): """Parse *bibfile* (see :meth:`parse_bibfile`), and store the parsed data, along with modification time *mtime*, in the bibtex cache. :param bibfile: The bib file name. :type bibfile: ``str`` :param mtime: The bib file's modification time. :type mtime: ``float`` :return: The parsed bibliography data. :rtype: :class:`pybtex.database.BibliographyData` """ data = self.parse_bibfile(bibfile, encoding) env = self.state.document.settings.env env.bibtex_cache.bibfiles[bibfile] = BibfileCache( mtime=mtime, data=data) return data
[docs] def process_bibfile(self, bibfile, encoding): """Check if ``env.bibtex_cache.bibfiles[bibfile]`` is still up to date. If not, parse the *bibfile* (see :meth:`update_bibfile_cache`), and store parsed data in the bibtex cache. :param bibfile: The bib file name. :type bibfile: ``str`` :return: The parsed bibliography data. :rtype: :class:`pybtex.database.BibliographyData` """ env = self.state.document.settings.env cache = env.bibtex_cache.bibfiles # get modification time of bibfile try: mtime = os.path.getmtime(bibfile) except OSError: standout("could not open bibtex file {0}.".format(bibfile))) cache[bibfile] = BibfileCache( # dummy cache mtime=-float("inf"), data=BibliographyData()) return cache[bibfile].data # get cache and check if it is still up to date # if it is not up to date, parse the bibtex file # and store it in the cache bold("checking for {0} in bibtex cache... ".format(bibfile)), nonl=True) try: bibfile_cache = cache[bibfile] except KeyError:"not found") self.update_bibfile_cache(bibfile, mtime, encoding) else: if mtime != bibfile_cache.mtime:"out of date") self.update_bibfile_cache(bibfile, mtime, encoding) else:'up to date') return cache[bibfile].data