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/latest/lib/python3.11/site-packages/auto_intersphinx/catalog.json]

Default: /home/docs/checkouts/readthedocs.org/user_builds/auto-intersphinx/envs/latest/lib/python3.11/site-packages/auto_intersphinx/catalog.json

-M, --pypi-max-entries

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