From e6276fbc6634b08b61ef0fd712b56978c95bcba7 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Wed, 28 Aug 2024 20:58:11 +1200 Subject: [PATCH 1/4] Add GitHub issue template for documentation tasks. --- .github/ISSUE_TEMPLATE/documentation-task.md | 23 ++++++++++++++++++++ 1 file changed, 23 insertions(+) create mode 100644 .github/ISSUE_TEMPLATE/documentation-task.md diff --git a/.github/ISSUE_TEMPLATE/documentation-task.md b/.github/ISSUE_TEMPLATE/documentation-task.md new file mode 100644 index 00000000..ca7cb599 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/documentation-task.md @@ -0,0 +1,23 @@ +--- +name: Documentation Task +about: A tightly scoped task for adding or updating documentation. +title: '' +labels: '' +assignees: nathanjmcdougall + +--- + +**Motivation** +A clear and concise description of what benefit you would get from this documentation update or addition. + +**Key Area** +Specify the key area of the project that requires documentation, e.g. the function, the workflow, the developer experience, etc. + +**Objectives & Target Audience** +Outline the objectives of the documentation task and describe the target audience. Specify the type of documentation (e.g., API documentation, user guide, tutorial) and what aspect you are specifically trying to communicate. + +**Steps** +An outline of the steps required to create or update the documentation. Include details such as: + +- The specific content (e.g. text, code snippets, diagrams) to be added or updated. +- The specific affected files From bd37567a4cd406474e19b58510dd577f5e84271e Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Thu, 29 Aug 2024 23:36:44 +1200 Subject: [PATCH 2/4] Add Keeping Config Sections Synchronized section to README. --- README.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/README.md b/README.md index f6115b54..4a780a47 100644 --- a/README.md +++ b/README.md @@ -5,3 +5,37 @@ Automate Python package and project setup tasks that are otherwise performed man ## Development [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) + +### Terminology + +A usethis function will run a _workflow_. Some workflows add and configure _tools_, +others add and configure _source code_. Some allow you to _browse_ somewhere. + +### Keeping Config Sections Synchronized + +Tools are not configured independently from one another. For example, if we are using +pytest, we might want to enable the PTD rules in ruff, whereas if we are not using +pytest, it really doesn't make sense to do this. Another example would be shared config, +e.g. if two tools both need to know that the source code is in the `src` folder. One +last example is a tool that cannot be used at all without another, e.g. setuptools_scm +requires that we have setuptools in the first place. + +These three examples illustrate three scenarios of tool dependence: + +- Partial Dependency, +- Shared Dependency, and +- Full Dependency. + +Each usethis function is potentially the dependent for another, and itself might have +dependents. Both directions need to be considered when the function is designed and +tested. To aid with this, usethis functions record dependencies using a registration +system using a decorator, which allows us to form a graph structure for the dependency +relationships. + +Generally, information for tool configuration should be in `pyproject.toml` in the +appropriate section. In rare cases, it might be necessary to store information in a +`[tool.usethis]` section, although this is not yet clear. + +To maintain synchronization between tools, the registration allows us to track through +the chain of dependencies to ensure that all relevant re-configurations take place, if +any. From 3c141fd30f1117342632500034f8d6f989f7564e Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Mon, 2 Sep 2024 09:33:52 +1200 Subject: [PATCH 3/4] Add documentation for interface plan and synchronization approach. --- README.md | 38 +++++++++++--------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/README.md b/README.md index 4a780a47..7ea0ac68 100644 --- a/README.md +++ b/README.md @@ -6,36 +6,20 @@ Automate Python package and project setup tasks that are otherwise performed man [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) -### Terminology +### Plan for interface -A usethis function will run a _workflow_. Some workflows add and configure _tools_, -others add and configure _source code_. Some allow you to _browse_ somewhere. +The current interfaces are being considered: -### Keeping Config Sections Synchronized - -Tools are not configured independently from one another. For example, if we are using -pytest, we might want to enable the PTD rules in ruff, whereas if we are not using -pytest, it really doesn't make sense to do this. Another example would be shared config, -e.g. if two tools both need to know that the source code is in the `src` folder. One -last example is a tool that cannot be used at all without another, e.g. setuptools_scm -requires that we have setuptools in the first place. +- `usethis tool` to configure a tool, e.g. `usethis tool ruff`. Adding a tool will install it, as well as add relevant files and/or configuration to use the tool. Tools can interact, for example if you run `usethis tool pytest` it wo;; install `pytest`, add it as a testing dependency, etc. but if you then run `usethis tool ruff` then `usethis` will strategically configure `pytest` with `pytest`-specific linter rules. Also vice-versa - if you already have ruff configured but then run `usethis tool pytest`, then `usethis` will strategically add new ruff configuration to reflect the fact you are now using `pytest`. In this way, `usethis` calls are order-invariant. +- `usethis badge` to add various badges. Note that you can often get the badge with `usethis tool ... --badge` when available for a tool. +- `usethis browse` to browse something, e.g. `usethis browse pypi ruff` would open the URL to the PyPI page for `ruff` in the browser. +- `usethis license` to choose a license, e.g. `usethis license mit` to use the MIT license. +- `usethis file` to create a python file at the specifified location. Add the `--test` flag to create a corresponding test file in the `tests` directory. -These three examples illustrate three scenarios of tool dependence: - -- Partial Dependency, -- Shared Dependency, and -- Full Dependency. +### Keeping Config Sections Synchronized -Each usethis function is potentially the dependent for another, and itself might have -dependents. Both directions need to be considered when the function is designed and -tested. To aid with this, usethis functions record dependencies using a registration -system using a decorator, which allows us to form a graph structure for the dependency -relationships. +Tools are not configured independently from one another. For example, if we are using pytest, we might want to enable the PTD rules in ruff, whereas if we are not using pytest, it really doesn't make sense to do this. Another example would be shared config, e.g. if two tools both need to know that the source code is in the `src` folder. One last example is a tool that cannot be used at all without another, e.g. `setuptools_scm` requires that we have setuptools in the first place. -Generally, information for tool configuration should be in `pyproject.toml` in the -appropriate section. In rare cases, it might be necessary to store information in a -`[tool.usethis]` section, although this is not yet clear. +Each usethis function is potentially the dependent for another, and itself might have dependents. Both directions need to be considered when the function is designed and tested. In general, functions need to be able to read configuration to determine which actions to take, and then they need robust write functionality to extend existing config and append to existing files. -To maintain synchronization between tools, the registration allows us to track through -the chain of dependencies to ensure that all relevant re-configurations take place, if -any. +Generally, information for tool configuration should be in `pyproject.toml` in the appropriate section. In rare cases, it might be necessary to store information in a `[tool.usethis]` section, although this is not yet clear. From 74689b3212fcf1f6eb368baea96bfdd576db7be0 Mon Sep 17 00:00:00 2001 From: Nathan McDougall Date: Mon, 2 Sep 2024 10:11:10 +1200 Subject: [PATCH 4/4] Add worked example for tool config sync. --- README.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ea0ac68..092bb24a 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Automate Python package and project setup tasks that are otherwise performed man [![uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json)](https://github.com/astral-sh/uv) -### Plan for interface +### Hypothetical Interface The current interfaces are being considered: @@ -15,6 +15,7 @@ The current interfaces are being considered: - `usethis browse` to browse something, e.g. `usethis browse pypi ruff` would open the URL to the PyPI page for `ruff` in the browser. - `usethis license` to choose a license, e.g. `usethis license mit` to use the MIT license. - `usethis file` to create a python file at the specifified location. Add the `--test` flag to create a corresponding test file in the `tests` directory. +- `usethis package` to configure the packages distributed by your project. ### Keeping Config Sections Synchronized @@ -23,3 +24,7 @@ Tools are not configured independently from one another. For example, if we are Each usethis function is potentially the dependent for another, and itself might have dependents. Both directions need to be considered when the function is designed and tested. In general, functions need to be able to read configuration to determine which actions to take, and then they need robust write functionality to extend existing config and append to existing files. Generally, information for tool configuration should be in `pyproject.toml` in the appropriate section. In rare cases, it might be necessary to store information in a `[tool.usethis]` section, although this is not yet clear. + +#### Worked Example + +We might run `usethis package` to make a distribution package associated with the project. This will be stored in the `packages` list in `[tool.setuptools]` in `pyproject.toml`. Then `usethis tool deptry` to set up deptry. This will add config to `pyproject.toml` for deptry, including ignoring the rule code DEP001 specifically for the packages listed by `usethis package`. If we added a new package with `usethis package --name other_package` then the deptry configuration would be extended to include this new package.