Skip to content

Commit

Permalink
doc: auto-gen config reference doc
Browse files Browse the repository at this point in the history 
Close #2645

Signed-off-by: Frost Ming <[email protected]>
  • Loading branch information
@frostming
frostming committed Feb 22, 2024
1 parent 0275813 commit df04fb6
Show file tree
Hide file tree
Showing 2 changed files with 15 additions and 34 deletions.
48 changes: 14 additions & 34 deletions docs/docs/reference/configuration.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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 | `<default config location on OS>/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.<name>.url` | The URL of custom package source | `https://pypi.org/simple` | Yes | |
| `pypi.<name>.username` | The username to access custom source | | Yes | |
| `pypi.<name>.password` | The password to access custom source | | Yes | |
| `pypi.<name>.type` | `index` or `find_links` | `index` | Yes | |
| `pypi.<name>.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 | `<default data location on OS>/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.<name>.url` | The URL of custom package source | `https://pypi.org/simple` | Yes | |
| `repository.<name>.username` | The username to access custom repository | | Yes | |
| `repository.<name>.password` | The password to access custom repository | | Yes | |
| `repository.<name>.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.<name>.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._
1 change: 1 addition & 0 deletions news/2645.doc.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Auto-gen configuration reference documentation.

0 comments on commit df04fb6

Please sign in to comment.