Command-line Interface#
This section includes information for using scripts shipped with
auto-intersphinx
.
auto-intersphinx#
Commands to handle sphinx catalogs.
Sub-commands:
check-packages: Discover documentation cross-references for packages
dump-objects: Dumps all the objects given an (inter) Sphinx inventory URL
update-catalog: Discover documentation cross-references for packages
usage: auto-intersphinx [-h] {check-packages,dump-objects,update-catalog} ...
check-packages#
Discover documentation cross-references for packages
usage: auto-intersphinx check-packages [-h] [-v] [-S] [-E] [-R] [-P]
[-M PYPI_MAX_ENTRIES] [-k] [-u USER]
packages [packages ...]
Positional Arguments#
- packages
Names of packages to check - specify one or more
Named Arguments#
- -v, --verbose
Can be set multiple times to increase console verbosity
Default: 0
- -S, --no-builtin
If set, then do not check own catalog
Default: False
- -E, --no-environment
If set, then do not check the current environment package documentation
Default: False
- -R, --no-rtd
If set, then do not check readthedocs.org for package documentation
Default: False
- -P, --no-pypi
If set, then do not check PyPI for package documentation
Default: False
- -M, --pypi-max-entries
The maximum number of entries to lookup in PyPI. A value of zero will download only the main package information and will hit PyPI only once. A value bigger than zero will download at most the information from the last
max_entries
releases. Finally, a negative value will imply the download of all available releases.Default: 0
- -k, --keep-going
If set, then do not stop at first found reference (such as auto-intersphinx would do), but rather keep searching for all references.
Default: False
- -u, --user
If set, then also checks the local user-catalog at the specified path
examples:
Checks internal catalog, Python environment, readthedocs.org and PyPI for package “requests”:
auto-intersphinx check-packages requests
Checks internal and user catalog, Python environment, readthedocs.org and PyPI for package “requests”:
auto-intersphinx check-packages --user=doc/catalog.json requests
Skip internal catalog checks when running for package “requests” (checks readthedocs.org and PyPI only):
auto-intersphinx check-packages --no-builtin requests
Keep looking for references in all available places (do not stop when first finds a documentation link, such as the extension does):
auto-intersphinx check-packages --keep-going requests
dump-objects#
Dumps objects documented in a Sphinx inventory URL
usage: auto-intersphinx dump-objects [-h] [-v] [url ...]
Positional Arguments#
- url
objects.inv
URL to parse and dump (can refer to a local file)Default: []
Named Arguments#
- -v, --verbose
Can be set multiple times to increase console verbosity
Default: 0
examples:
Dumps objects documented in a local Sphinx build:
auto-intersphinx dump-objects html/objects.inv
Dumps objects documented in python 3.x:
auto-intersphinx dump-objects https://docs.python.org/3/objects.inv
Dumps objects documented in numpy:
auto-intersphinx dump-objects https://docs.scipy.org/doc/numpy/objects.inv
update-catalog#
Updates catalog of intersphinx cross-references
usage: auto-intersphinx update-catalog [-h] [-v] [--self] [-o OUTPUT]
[-c CATALOG] [-M PYPI_MAX_ENTRIES] [-k]
[packages ...]
Positional Arguments#
- packages
Location of the reference package list to load to populate catalog. If not specified, then does not update anything (unless –self is set, of course). This argument may take multiple inputs. Each input may be a filename, which contains package lists, a remote http/https file, or a package name.
Default: []
Named Arguments#
- -v, --verbose
Can be set multiple times to increase console verbosity
Default: 0
- --self
If set, then self-updates catalog entries
Default: False
- -o, --output
If set, then dump the existing catalog to an output file
- -c, --catalog
Location of the catalog to update [default: /home/docs/checkouts/readthedocs.org/user_builds/auto-intersphinx/envs/v1.0.2/lib/python3.10/site-packages/auto_intersphinx/catalog.json]
Default: /home/docs/checkouts/readthedocs.org/user_builds/auto-intersphinx/envs/v1.0.2/lib/python3.10/site-packages/auto_intersphinx/catalog.json
- -M, --pypi-max-entries
The maximum number of entries to lookup in PyPI. A value of zero will download only the main package information and will hit PyPI only once. A value bigger than zero will download at most the information from the last
max_entries
releases. Finally, a negative value will imply the download of all available releases.Default: 0
- -k, --keep-going
If set, then do not stop at first found reference (such as auto-intersphinx would do), but rather keep searching for all references.
Default: False
examples:
Updates numpy and scipy from the internal catalog, dumps new catalog to stdout
auto-intersphinx update-catalog numpy scipy
Self-update internal catalog:
auto-intersphinx update-catalog --self
Refresh internal catalog from a remote pip-constraints.txt file:
auto-intersphinx update-catalog https://gitlab.idiap.ch/software/idiap-citools/-/raw/main/src/citools/data/pip-constraints.txt
Run local tests without modifying the package catalog:
auto-intersphinx update-catalog --output=testout.json