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.
biblatex-key-convert: checks if some known BibLaTeX keys should be converted based on their values (e.g. a numeric “issue” is better used as a “number”).
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.
field-type: checks the type of fields provided by document-field-types (and document-field-types-extend), e.g. year should be an int. Lists can be automatically fixed (by splitting or joining) using the doctor-field-type-separator setting.
keys-missing: checks that the keys provided by doctor-keys-missing-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).
string-cleaner: checks that strings do contain various undesired characters (e.g. newlines in titles) and other general style issues (double whitespace).

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 --checks 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 --checks html-tags einstein
The --explain flag can be used to give additional details of checks that failed. This check (and some others) also has automatic fixers. Here, we can just remove all the HTML tags by writing:
papis doctor --fix --checks html-tags einstein
If an automatic fix is not possible, some checks also have suggested commands or tips to fix issues. For example, if a key does not exist in the document, it can suggest editing the file to add it:
papis doctor --suggestion --checks keys-missing 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 --checks keys-missing 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.

Usage

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.

--list-checks: List all supported checks.

--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