3.3. Options#

The control center provides more than four thousand options structured into a number of top-level key-value pairs covering every aspect of the project from general descriptors and metadata to various workflow setting and tool-specific configurations (Table 3.3.1). All available options are documented in the API Reference, which is automatically generated from JSON Schemas that define the structure of control center configurations and are used to validate user settings during synchronization events.

Table 3.3.1 An overview of main control center configuration categories.#

Category

Examples

Descriptors

Project descriptors like name, title, abstract, keywords, highlights, and theme colors.

Metadata

Project metadata such as license, copyright, citation, language, funding, and team.

Packages

Python package and test suite configurations including build settings, dependencies, and entry points.

Documentation

Dynamic document definitions, discussions categories, and website configurations.

Issue Tracking

Configurations for issues and pull requests, including issue forms, protocols, and labels.

Version Control

General configurations for the GitHub/Git repository and its branches, tags, files, and commits.

Workflow

Workflow configurations such as role definitions and settings for various Continuous pipelines and development tools.

3.3.1. Preconfiguration#

Almost all available configurations are set to sensible defaults, requiring most users to only specify a handful of project descriptors like name, title, and keywords. For all generic configurations such as tool settings, default values are provided based on the latest standards and best practices. For other project-specific configurations, defaults are included as dynamic templates that use simple project descriptors and metadata to automatically generate more complex configurations. Examples include license, citation, and various documentation files like READMEs and community health files.

The default values are provided in two different places: Some are included directly within the JSON Schemas, and are thus documented in the API Reference. These defaults are automatically applied when the input configurations are being validated against the schema. Additional default values are provided in the control center configuration files included in the PyPackIT repository template at .control/. These default values are not documented in the API Reference, but can be simply reviewed by navigating your project’s control center. The reason for not including all default values in the schemas is that many PyPackIT functionalities can be disabled by omitting the corresponding configurations. These are not included in the schemas, so users can disable features they do not need simply by removing the corresponding configurations from the provided configuration files.

3.3.2. Augmentation#

Another way PyPackIT minimizes manual configurations is by generating and retrieving project-specific statistics and data at runtime. For example:

  • Github repository metadata like name, ID, owner, creation date, URL, and other details are automatically retrieved from the GitHub API and added to $.repo.

  • Team member data including name, email, affiliation, bio, social accounts, and other available information are also retrieved from the GitHub API and to each member under $.team.

  • License information such as license full texts, copyright notices, and various other metadata are automatically retrieved from the SPDX database and added to $.license, requiring users to only define an SPDX license expression for their project.

  • Project statistics such as released versions and their details, active branches and their configurations, and a list of dynamically maintained resources are automatically generated by analyzing your git repository and extracting data from each branch’s configuration files. These are added to $.project, and are used for example in issue form definitions to dynamically reference available release versions, supported Python versions, and other release-specific information for users to select from when submitting an issue.

  • Literature citations can be automatically retrieved. PyPackIT can use the ORCiD API to retrieve all publications of an author, and for each publication, it only needs a DOI to fetch full metadata and citation information from the Crossref DOI APIs.

3.3.3. Customization#

Most control center options only accept a set of predefined data structures and values, as described in the API Reference. This is to ensure that all configurations and data are correctly specified by the user, by validating them against a predefined schema.

To enable custom user-defined configurations, PyPackIT allows two special keys that accept arbitrary values: __data__ and __temp__. These keys can be added under any mapping in the control center configurations, except those that already accept additional properties. For example, you can define a top-level custom key at $.__data__ and add all your custom configurations under it:

Code 3.3.3.1 Defining custom configurations at $.__data__#
__data__:
  my_custom_sequence:
    - 1
    - 2
    - 3
  my_custom_mapping:
    a: true
    b: false
  my_custom_string: Hello World

There two differences between __data__ and __temp__ keys (see templating for more details):

  1. Relative paths in templates defined under __temp__ are resolved against the path where that template is referenced, not where it is defined.

  2. __temp__ key-value pairs are not included in the output metadata file.

In other words, __temp__ is only meant for intermediate configurations that are used to generate other settings during synchronization events.