Doctor

The doctor command checks for the overall health of your library.

There are many checks implemented and some others that you can add yourself through the Python configuration file (these cannot be added through the static configuration file). Currently, the following checks are implemented

  • biblatex-key-alias: checks that the document does not contain any known key (or field in BibLaTeX) from bibtex_key_aliases.

  • biblatex-required-keys: checks that the document contains all the required keys for its type. In BibLaTeX, each type (e.g. article) has a set of required (or at least strongly recommended) keys that it needs to be adequately shown in the bibliography.

  • biblatex-type-alias: checks that the BibLaTeX type of the document is not a known type alias (usually defined for backwards compatibility reasons), as defined by bibtex_type_aliases.

  • bibtex-type: checks that the document type matches a known BibLaTeX type from papis.bibtex.bibtex_types.

  • duplicated-keys: checks that the keys provided by doctor-duplicated-keys-keys are not present in multiple documents. This is mainly meant to be used to check the ref key or other similar keys that are meant to be unique.

  • duplicated-values: checks if the keys provided by doctor-duplicated-values-keys have any duplicated values. The keys are expected to be lists, e.g. files.

  • files: checks whether all the document files exist on the filesystem.

  • html-codes: checks that no HTML codes (e.g. &) appear in the keys provided by doctor-html-codes-keys.

  • html-tags: checks that no HTML or XML tags (e.g. <a>) appear in the keys provided by doctor-html-tags-keys.

  • key-type: checks the type of keys provided by doctor-key-type-check-keys, e.g. year should be an int. Lists can be automatically fixed (by splitting or joining) using the doctor-key-type-check-separator setting.

  • keys-exist: checks that the keys provided by doctor-keys-exist-keys exist in the document.

  • refs: checks that the document has a valid reference (i.e. one that would be accepted by BibTeX and only contains valid characters).

If any custom checks are implemented, you can get a complete list at runtime from

papis list --doctors

Examples

  • To run all available checks over all available documents in the library use

    papis doctor --all-checks --all

    This will likely generate too many results, but it can be useful to output in JSON

    papis doctor --all-checks --all --json

  • To check if all the files of a document are present, use

    papis doctor --check files einstein

  • To check if any unwanted HTML tags are present in your documents (especially abstracts can be full of additional HTML or XML tags) use

    papis doctor --explain --check html-tags einstein

    The --explain flag can be used to give additional details of checks that failed. Some fixes such as this also have automatic fixers. Here, we can just remove all the HTML tags by writing

    papis doctor --fix --check html-tags einstein

  • If an automatic fix is not possible, some checks also have suggested commands or tips to fix the issue that was found. For example, if a key does not exist in the document, it can suggest editing the file to add it.

    papis doctor --suggestion --check keys-exist einstein
>> Suggestion: papis edit --doc-folder /path/to/folder

    If this is the case, you can also run the following to automatically open the info.yaml file for editing more complex changes

    papis doctor --edit --check keys-exist einstein

Implementing additional checks

A check is just a function that takes a document and returns a list of errors. A skeleton implementation that gets added to config.py (see Python configuration file) can be implemented as follows

from papis.commands.doctor import Error, register_check

def my_custom_check(doc) -> List[Error]:
    ...

register_check("my-custom-check", my_custom_check)

Command-line Interface

Check for common problems in documents

papis doctor [OPTIONS] [QUERY]

Options

-h, --help

Show this message and exit.

--sort <FIELD>

Sort documents with respect to the FIELD

--reverse

Reverse sort order

-t, --checks <_checks>

Checks to run on every document.

Options:

files | keys-exist | duplicated-keys | duplicated-values | bibtex-type | biblatex-type-alias | biblatex-key-alias | biblatex-required-keys | refs | html-codes | html-tags | key-type

--json

Output the results in json format

--fix

Auto fix the errors with the auto fixer mechanism

-s, --suggest

Suggest commands to be run for resolution

-e, --explain

Give a short message for the reason of the error

--edit

Edit every file with the edit command.

-a, --all

Apply action to all matching documents

--doc-folder <doc_folder>

Document folder on which to apply action

--all-checks

Run all available checks (ignores –checks)

Arguments

QUERY

Optional argument