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
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: checks that the document type matches a known BibLaTeX type from
duplicated-keys: checks that the keys provided by
doctor-duplicated-keys-keysare not present in multiple documents. This is mainly meant to be used to check the
refkey or other similar keys that are meant to be unique.
duplicated-values: checks if the keys provided by
doctor-duplicated-values-keyshave any duplicated values. The keys are expected to be lists, e.g.
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
html-tags: checks that no HTML or XML tags (e.g.
<a>) appear in the keys provided by
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
keys-exist: checks that the keys provided by
doctor-keys-exist-keysexist 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
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
--explainflag 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.yamlfile 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
(see Python configuration file) can be implemented as follows
from papis.commands.doctor import Error, register_check
def my_custom_check(doc) -> List[Error]:
Check for common problems in documents
papis doctor [OPTIONS] [QUERY]
- -h, --help
Show this message and exit.
- --sort <FIELD>
Sort documents with respect to the FIELD
Reverse sort order
- -t, --checks <_checks>
Checks to run on every document.
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
Output the results in json format
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 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
Run all available checks (ignores –checks)