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) frombibtex_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 bybibtex_type_aliases
.bibtex-type
: checks that the document type matches a known BibLaTeX type frompapis.bibtex.bibtex_types
.duplicated-keys
: checks that the keys provided bydoctor-duplicated-keys-keys
are not present in multiple documents. This is mainly meant to be used to check theref
key or other similar keys that are meant to be unique.duplicated-values
: checks if the keys provided bydoctor-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 bydoctor-html-codes-keys
.html-tags
: checks that no HTML or XML tags (e.g.<a>
) appear in the keys provided bydoctor-html-tags-keys
.key-type
: checks the type of keys provided bydoctor-key-type-keys
, e.g. year should be anint
. Lists can be automatically fixed (by splitting or joining) using thedoctor-key-type-separator
setting.keys-missing
: checks that the keys provided bydoctor-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).
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 writingpapis 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-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 changespapis doctor --edit --check 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
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-missing | duplicated-keys | duplicated-values | bibtex-type | biblatex-type-alias | biblatex-key-alias | biblatex-required-keys | refs | html-codes | html-tags | key-type | keys-exist
- --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