From df04fb674b96f76bd29dafef8895fa41d937f872 Mon Sep 17 00:00:00 2001 From: Frost Ming Date: Thu, 22 Feb 2024 12:29:30 +0800 Subject: [PATCH] doc: auto-gen config reference doc Close #2645 Signed-off-by: Frost Ming --- docs/docs/reference/configuration.md | 48 ++++++++-------------------- news/2645.doc.md | 1 + 2 files changed, 15 insertions(+), 34 deletions(-) create mode 100644 news/2645.doc.md diff --git a/docs/docs/reference/configuration.md b/docs/docs/reference/configuration.md index c7c19814a5..5121a2d24f 100644 --- a/docs/docs/reference/configuration.md +++ b/docs/docs/reference/configuration.md @@ -31,48 +31,28 @@ pdm config theme.success '#51c7bd' The following configuration items can be retrieved and modified by [`pdm config`][pdm-config] command. -| Config Item | Description | Default Value | Available in Project | Env var | -| --------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------- | -------------------- |---------------------------| -| `build_isolation` | Isolate the build environment from the project environment | Yes | Yes | `PDM_BUILD_ISOLATION` | -| `cache_dir` | The root directory of cached files | The default cache location on OS | No | `PDM_CACHE_DIR` | -| `check_update` | Check if there is any newer version available | True | No | `PDM_CHECK_UPDATE` | -| `global_project.fallback` | Use the global project implicitly if no local project is found | `False` | No | | -| `global_project.fallback_verbose` | If True show message when global project is used implicitly | `True` | No | | -| `global_project.path` | The path to the global project | `/global-project` | No | | -| `global_project.user_site` | Whether to install to user site | `False` | No | | -| `install.cache` | Enable caching of wheel installations | False | Yes | | -| `install.cache_method` | Specify how to create links to the caches(`symlink/symlink_individual/hardlink/pth`) | `symlink` | Yes | | -| `install.parallel` | Whether to perform installation and uninstallation in parallel | `True` | Yes | `PDM_PARALLEL_INSTALL` | -| `python.use_pyenv` | Use the pyenv interpreter | `True` | Yes | | -| `python.use_venv` | Use virtual environments when available | `True` | Yes | `PDM_USE_VENV` | -| `python.providers` | List of python provider names for findpython | All providers supported by findpython | Yes | | -| `pypi.url` | The URL of PyPI mirror | `https://pypi.org/simple` | Yes | `PDM_PYPI_URL` | -| `pypi.username` | The username to access PyPI | | Yes | `PDM_PYPI_USERNAME` | -| `pypi.password` | The password to access PyPI | | Yes | `PDM_PYPI_PASSWORD` | -| `pypi.ignore_stored_index` | Ignore the configured indexes | `False` | Yes | `PDM_IGNORE_STORED_INDEX` | -| `pypi.ca_certs` | Path to a PEM-encoded CA cert bundle (used for server cert verification) | The CA certificates from [certifi](https://pypi.org/project/certifi/) | Yes | | -| `pypi.client_cert` | Path to a PEM-encoded client cert and optional key | | No | | -| `pypi.client_key` | Path to a PEM-encoded client cert private key, if not in pypi.client_cert | | No | | -| `pypi.verify_ssl` | Verify SSL certificate when query PyPI | `True` | Yes | | -| `pypi.json_api` | Consult PyPI's JSON API for package metadata | `False` | Yes | `PDM_PYPI_JSON_API` | +!!! note "Environment Variable Overrides" + If the corresponding env var is set, the value will take precedence over what is saved in the config file. + + +```python exec="on" +from pdm.project.config import Config + +print("| Config Item | Description | Default Value | Available in Project | Env var |") +print("| --- | --- | --- | --- | --- |") +for key, value in Config._config_map.items(): + print(f"| `{key}` | {value.description} | {('`%s`' % value.default) if value.should_show() else ''} | {'No' if value.global_only else 'Yes'} | {('`%s`' % value.env_var) if value.env_var else ''} |") +print("""\ | `pypi..url` | The URL of custom package source | `https://pypi.org/simple` | Yes | | | `pypi..username` | The username to access custom source | | Yes | | | `pypi..password` | The password to access custom source | | Yes | | | `pypi..type` | `index` or `find_links` | `index` | Yes | | | `pypi..verify_ssl` | Verify SSL certificate when query custom source | `True` | Yes | | -| `strategy.save` | Specify how to save versions when a package is added | `minimum`(can be: `exact`, `wildcard`, `minimum`, `compatible`) | Yes | | -| `strategy.update` | The default strategy for updating packages | `reuse`(can be : `eager`, `reuse`, `all`, `reuse-installed`) | Yes | | -| `strategy.resolve_max_rounds` | Specify the max rounds of resolution process | 10000 | Yes | `PDM_RESOLVE_MAX_ROUNDS` | -| `strategy.inherit_metadata` | Inherit the groups and markers from parents for each package | `True` | Yes | | -| `venv.location` | Parent directory for virtualenvs | `/venvs` | No | | -| `venv.backend` | Default backend to create virtualenv | `virtualenv` | Yes | `PDM_VENV_BACKEND` | -| `venv.prompt` | Formatted string to be displayed in the prompt when virtualenv is active | `{project_name}-{python_version}` | Yes | `PDM_VENV_PROMPT` | -| `venv.in_project` | Create virtualenv in `.venv` under project root | `True` | Yes | `PDM_VENV_IN_PROJECT` | -| `venv.with_pip` | Install pip when creating a new venv | `False` | Yes | `PDM_VENV_WITH_PIP` | | `repository..url` | The URL of custom package source | `https://pypi.org/simple` | Yes | | | `repository..username` | The username to access custom repository | | Yes | | | `repository..password` | The password to access custom repository | | Yes | | | `repository..ca_certs` | Path to a PEM-encoded CA cert bundle (used for server cert verification) | The CA certificates from [certifi](https://pypi.org/project/certifi/) | Yes | | | `repository..verify_ssl` | Verify SSL certificate when uploading to repository | `True` | Yes | | +""") +``` -_If the corresponding env var is set, the value will take precedence over what is saved in the config file._ diff --git a/news/2645.doc.md b/news/2645.doc.md new file mode 100644 index 0000000000..4db2464e1c --- /dev/null +++ b/news/2645.doc.md @@ -0,0 +1 @@ +Auto-gen configuration reference documentation.