From 7ad4f889c48c5a572d269889f7f38d3414b8c54f Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 29 Oct 2024 09:48:07 +0000 Subject: [PATCH 01/10] Tidy up README Move all developer instructions out from README and rework/update the instructions. Disable markdownlint rule MD033 globally. --- .pre-commit-config.yaml | 1 + CONTRIBUTING.md | 78 ++++++++++++ README.md | 271 ++++++++++++++++++++-------------------- 3 files changed, 217 insertions(+), 133 deletions(-) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 8541cb80..0a438a03 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,6 +15,7 @@ repos: - id: markdownlint-fix args: - --dot + - --disable=MD033 - repo: https://github.com/Lucas-C/pre-commit-hooks rev: v1.5.5 hooks: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3bc57e5f..52f8f4c4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -39,3 +39,81 @@ To contribute a change, please: [Research software engineers]: https://society-rse.org/about/history [@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations + +## Notes for developers + +
Click to expand... + +First, clone repository + +- (Optional) Generate your SSH keys as suggested + [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) +- (Optional) GitHub CLI as suggested + [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account?tool=cli) +- Clone the repository by typing (or copying) the following line in a terminal + at your selected path in your machine: + +```sh +git clone git@github.com:UCL-ARC/python-tooling.git +cd python-tooling +``` + +### Developing the cookiecutter template + +- To create and remove your virtual environment + + ```sh + uv venv + source .venv/bin/activate + # do your work + deactivate + ``` + +- To run template in the same path of this repo. We do a test cookiecut of a + dummy package and install it to ensure the template setup works. + + ```sh + cookiecutter . + cd python-template + git init + uv pip install -e ".[dev]" + ``` + +- To run cookiecutter using a specific branch of the template: + + ```sh + cookiecutter https://github.com/UCL-ARC/python-tooling --checkout + ``` + +- To run the tests locally: + + ```sh + pytest -s + ``` + +### Developing the recommended tooling pages + +Pages all live in the +[docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages) +sub-directory, and are written in markdown. + +To build the webpage locally (for testing) + +1. [Install jekyll](https://jekyllrb.com/docs/installation) +2. Run `bundle install` from the `docs/` directory of this repository to + install dependencies. +3. Run `bundle exec jekyll serve` from the root directory of this repository. + This should fire up a local web server and tell you its address. By default + the server will automatically refresh the HTML pages if any changes are made + to the markdown sources. + +See the [jekyll docs](https://jekyllrb.com/docs) for more info. + +
+ +If you have this repo locally (this may be the case if you are developing), +you can run the following: + +```sh +cookiecutter /path/to/your/checkout/of/python-tooling --checkout latest +``` diff --git a/README.md b/README.md index fa5a2a69..d7475573 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +
UCL ARC Python tooling logo

UCL ARC Python Recommendations

@@ -19,12 +19,148 @@ Python packages with our recommended tooling set up and ready to go. > package template (e.g., [`scikit-hep`](https://github.com/scikit-hep/cookie)), > we recommend using their template instead of this one. +## Tutorial + +Some quick instructions for using our template are below. +We also have a pedagogical [tutorial](./tutorial.md) that has been given in a couple of workshops geared towards researchers at UCL. + +## Using our template + +If you have [uv] installed, you can use our template with the following one-liner: + +```sh +uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest +``` + +You can also [install cookiecutter]. +Do this if you don't use [uv], or if you're likely to want to use cookiecutter again. +Here's the way we install it: + +```sh +uv tool install cookiecutter +``` + +Then you'll need to run cookiecutter with our template: + +```sh +cookiecutter gh:ucl-arc/python-tooling --checkout latest +``` + +When [cookiecutter] runs, it will ask you a series of questions to configure your project. +Type the answer or hit return without typing anything to use the default option (shown in parenthesis). +At the end, it will print some more follow-up information in the terminal for things like creating a remote repository and making a website for your package. + +Here's an example run through + +
Click to expand... + +```sh +uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest + [1/14] Given name(s) of package author (Eva Lu): Grace + [2/14] Family name(s) of package author (Ator): Hopper + [3/14] Email address for package author - will be part of package metadata +(grace.hopper@ucl.ac.uk): + [4/14] Name of project - may contain spaces (Python Template): Example Research Software Project + [5/14] 'Slugified' project name for use in URLs - dash-case recommended +(example-research-software-project): + [6/14] Name for Python package - snake_case recommended +(example_research_software_project): ersp + [7/14] Short description of the project (A cookiecutter package with UCL ARC +recommendations.): An example project. + [8/14] Initialise project directory as a Git repository? [y/n] (y): y + [9/14] Automatically deploy HTML docs to GitHub Pages on pushes to main? [y/n] +(y): y + [10/14] GitHub user or organization name which will be owner of repository +(grace-hopper): UCL-ARC + [11/14] Minimum Python version supported by package + 1 - 3.11 + 2 - 3.12 + 3 - 3.13 + Choose from [1/2/3] (1): + [12/14] Maximum Python version supported by package + 1 - 3.13 + 2 - 3.12 + 3 - 3.11 + Choose from [1/2/3] (1): + [13/14] Which open-source license to release package under + 1 - MIT + 2 - BSD-3 + 3 - GPL-3.0 + Choose from [1/2/3] (1): 1 + [14/14] Organisation(s) to acknowledge for funding of project (optional) (): +Initialized empty Git repository in /Users/scnlf/example-research-software-project/.git/ +GitHub CLI detected, you can create a repo with the following: + +gh repo create UCL-ARC/example-research-software-project -d "An example project." --public -r origin --source example-research-software-project + +The 'Documentation' GitHub Actions workflow has been set up to push the built HTML documentation to a branch gh-pages on pushes to main for deploying as a GitHub Pages website. To allow the GitHub Actions bot to push to the gh-pages branch you need to enable 'Read and write permissions' under 'Workflow permissions' at + +https://github.com/UCL-ARC/example-research-software-project/settings/actions + +After the 'Documentation' workflow has successfully completed at least once you will also need to configure the repository to deploy a GitHub pages site from the content on the gh-pages branch by going to + +https://github.com/UCL-ARC/example-research-software-project/settings/pages + +and under 'Built and deployment' selecting 'Deploy from a branch' for the 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, leaving the branch path drop-down with its default value of '/ (root)'. +``` + +
+ +
+ +This will create a project directory structure. + +
Click to expand... + +```sh +tree example-research-software-project +example-research-software-project +├── CITATION.cff +├── LICENSE.md +├── README.md +├── docs +│   ├── LICENSE.md +│   ├── api.md +│   └── index.md +├── mkdocs.yml +├── pyproject.toml +├── schemas +│   └── github-issue-forms.json +├── src +│   └── ersp +│   └── __init__.py +└── tests + └── test_dummy.py + +6 directories, 11 files +``` + +
+ +
+ + + +To work on your project, initialise a `git` repository and _install_ your new package editable mode. +You probably want to do this in a [virtual environment](./docs/pages/virtual.md). +The comments show how to do this in [uv] with `uv venv`: + +```sh +cd example-research-software-project +git init +# uv venv +# source .venv/bin/activate +uv pip install -e ".[dev]" +``` + [website]: https://github-pages.arc.ucl.ac.uk/python-tooling [UCL ARC]: https://ucl.ac.uk/arc -[cookiecutter]: https://libraries.io/pypi/cookiecutter +[cookiecutter]: https://cookiecutter.readthedocs.io/en/stable +[install cookiecutter]: https://cookiecutter.readthedocs.io/en/stable/README.html#installation +[uv]: https://docs.astral.sh/uv ## Contributors @@ -68,134 +204,3 @@ Python packages with our recommended tooling set up and ready to go. - -## Using this template - -Some quick instructions for using our template are below. -We also have a detailed [tutorial](tutorial.md) that has been given in a couple of workshops geared towards researchers at UCL. -The tutorial goes into much more pedagogical detail, it both describes using the template to create a package -and how to use the newly created package with some of the tools included. - -1. Install [cookiecutter] in a `uv venv` or `conda` environment (commented lines for - `uv venv` example). - - ```sh - # uv venv # creates a .venv directory wherever you are - # source ./.venv/bin/activate - uv pip install cookiecutter - ``` - -2. Run cookiecutter in the desired directory - - ```sh - cookiecutter gh:ucl-arc/python-tooling --checkout latest - ``` - - If you have this repo locally (this may be the case if you are developing), - you can run the following: - - ```sh - cookiecutter /path/to/your/checkout/of/python-tooling --checkout latest - ``` - -3. A series of questions will pop up to configure the project. Type the answer - or hit return to use the default option (shown in parenthesis). - - Note that these project variables are defined in the `cookiecutter.json` - file. - -4. This will create a specific directory structure. - - For example, for a project with the following variables: - - ```yaml - project_name [Python Template]: PROJECT_NAME - project_slug [python-template]: PROJECT_SLUG - package_name [python_template]: PACKAGE_NAME - ``` - -5. To work on your project, initialise a Git repository and _install_ it in - editable mode. - - ```sh - cd PROJECT_SLUG - git init - uv pip install -e ".[dev]" - ``` - -6. Build your package - - ```sh - python -m build - ``` - -## Notes for developers - -
Click to expand... - -First, clone repository - -- (Optional) Generate your SSH keys as suggested - [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) -- (Optional) GitHub CLI as suggested - [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account?tool=cli) -- Clone the repository by typing (or copying) the following line in a terminal - at your selected path in your machine: - -```sh -git clone git@github.com:UCL-ARC/python-tooling.git -cd python-tooling -``` - -### Developing the cookiecutter template - -- To create and remove your virtual environment - - ```sh - uv venv - source .venv/bin/activate - # do your work - deactivate - ``` - -- To run template in the same path of this repo. We do a test cookiecut of a - dummy package and install it to ensure the template setup works. - - ```sh - cookiecutter . - cd python-template - git init - uv pip install -e ".[dev]" - ``` - -- To run cookiecutter using a specific branch of the template: - - ```sh - cookiecutter https://github.com/UCL-ARC/python-tooling --checkout - ``` - -- To run the tests locally: - - ```sh - pytest -s - ``` - -### Developing the recommended tooling pages - -Pages all live in the -[docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages) -sub-directory, and are written in markdown. - -To build the webpage locally (for testing) - -1. [Install jekyll](https://jekyllrb.com/docs/installation) -2. Run `bundle install` from the `docs/` directory of this repository to - install dependencies. -3. Run `bundle exec jekyll serve` from the root directory of this repository. - This should fire up a local web server and tell you its address. By default - the server will automatically refresh the HTML pages if any changes are made - to the markdown sources. - -See the [jekyll docs](https://jekyllrb.com/docs) for more info. - -
From 4737b693e99c55e5b39b71001145a84571922c31 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 29 Oct 2024 09:57:39 +0000 Subject: [PATCH 02/10] Tidy up dev instructions. Remove duplicated. --- CONTRIBUTING.md | 88 +++++++++++++++---------------------------------- 1 file changed, 27 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 52f8f4c4..d6e525e3 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -29,67 +29,29 @@ To contribute a change, please: 6. If changes are requested, the PR author should address the comments, and then ask for review again. - - - -[website]: https://github-pages.arc.ucl.ac.uk/python-tooling -[UCL ARC]: https://ucl.ac.uk/arc -[open an issue]: https://github.com/UCL-ARC/python-tooling/issues/new/choose -[Discussions tab]: https://github.com/UCL-ARC/python-tooling/discussions -[Research software engineers]: https://society-rse.org/about/history -[@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations - - -## Notes for developers - -
Click to expand... - -First, clone repository +### Developing the cookiecutter template -- (Optional) Generate your SSH keys as suggested - [here](https://docs.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) -- (Optional) GitHub CLI as suggested - [here](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/adding-a-new-ssh-key-to-your-github-account?tool=cli) -- Clone the repository by typing (or copying) the following line in a terminal - at your selected path in your machine: +We quite like installing cookiecutter as a uv tool: ```sh -git clone git@github.com:UCL-ARC/python-tooling.git -cd python-tooling +uv tool install cookiecutter ``` -### Developing the cookiecutter template - -- To create and remove your virtual environment - - ```sh - uv venv - source .venv/bin/activate - # do your work - deactivate - ``` - -- To run template in the same path of this repo. We do a test cookiecut of a - dummy package and install it to ensure the template setup works. +To run cookiecutter using a specific branch of the template: - ```sh - cookiecutter . - cd python-template - git init - uv pip install -e ".[dev]" - ``` - -- To run cookiecutter using a specific branch of the template: +```sh +cookiecutter gh:UCL-ARC/python-tooling --checkout +``` - ```sh - cookiecutter https://github.com/UCL-ARC/python-tooling --checkout - ``` +If you have this repo locally (presumably the case if you're developing), you +can run the following: -- To run the tests locally: +```sh +cookiecutter /path/to/your/checkout/of/python-tooling --checkout +``` - ```sh - pytest -s - ``` +Perhaps obvious, you can omit the `--checkout` option if you're already on the +branch you want to test. ### Developing the recommended tooling pages @@ -99,7 +61,7 @@ sub-directory, and are written in markdown. To build the webpage locally (for testing) -1. [Install jekyll](https://jekyllrb.com/docs/installation) +1. [Install jekyll] 2. Run `bundle install` from the `docs/` directory of this repository to install dependencies. 3. Run `bundle exec jekyll serve` from the root directory of this repository. @@ -107,13 +69,17 @@ To build the webpage locally (for testing) the server will automatically refresh the HTML pages if any changes are made to the markdown sources. -See the [jekyll docs](https://jekyllrb.com/docs) for more info. +See the [jekyll docs] for more info. -
- -If you have this repo locally (this may be the case if you are developing), -you can run the following: + -```sh -cookiecutter /path/to/your/checkout/of/python-tooling --checkout latest -``` + +[website]: https://github-pages.arc.ucl.ac.uk/python-tooling +[UCL ARC]: https://ucl.ac.uk/arc +[open an issue]: https://github.com/UCL-ARC/python-tooling/issues/new/choose +[Discussions tab]: https://github.com/UCL-ARC/python-tooling/discussions +[Research software engineers]: https://society-rse.org/about/history +[@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations +[Install jekyll]: https://jekyllrb.com/docs/installation +[jekyll docs]: https://jekyllrb.com/docs + From e123e180378cfc86088e2622f6bcdc9d54eae31d Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Tue, 29 Oct 2024 11:38:55 +0000 Subject: [PATCH 03/10] Move suppression of MD033 into dotfile which I didn't notice. --- .markdownlint.yaml | 1 + .pre-commit-config.yaml | 1 - 2 files changed, 1 insertion(+), 1 deletion(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 02907b2b..979c36e4 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,2 +1,3 @@ --- MD013: false +MD033: false diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 0a438a03..8541cb80 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -15,7 +15,6 @@ repos: - id: markdownlint-fix args: - --dot - - --disable=MD033 - repo: https://github.com/Lucas-C/pre-commit-hooks rev: v1.5.5 hooks: From 2d5f0a7d22bd89c23008849f79477db3aba2fdbf Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Fri, 1 Nov 2024 08:32:51 +0000 Subject: [PATCH 04/10] @dstansby's language clarifications. Co-authored-by: David Stansby --- .markdownlint.yaml | 2 +- CONTRIBUTING.md | 8 ++++---- README.md | 2 +- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 979c36e4..8dca0820 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,3 +1,3 @@ --- MD013: false -MD033: false +MD033: false # no-inline-html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d6e525e3..67f3aabd 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -31,7 +31,7 @@ To contribute a change, please: ### Developing the cookiecutter template -We quite like installing cookiecutter as a uv tool: +We quite like installing cookiecutter as a [uv tool](https://docs.astral.sh/uv/guides/tools/), so it's available globally: ```sh uv tool install cookiecutter @@ -44,19 +44,19 @@ cookiecutter gh:UCL-ARC/python-tooling --checkout ``` If you have this repo locally (presumably the case if you're developing), you -can run the following: +can instead run the following: ```sh cookiecutter /path/to/your/checkout/of/python-tooling --checkout ``` -Perhaps obvious, you can omit the `--checkout` option if you're already on the +You can omit the `--checkout` option if you're already on the branch you want to test. ### Developing the recommended tooling pages Pages all live in the -[docs/pages](https://github.com/UCL-ARC/python-tooling/tree/main/docs/pages) +`docs/pages` sub-directory, and are written in markdown. To build the webpage locally (for testing) diff --git a/README.md b/README.md index d7475573..9af79bcd 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ If you have [uv] installed, you can use our template with the following one-line uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -You can also [install cookiecutter]. +Alternatively you can [install cookiecutter]. Do this if you don't use [uv], or if you're likely to want to use cookiecutter again. Here's the way we install it: From 3900cbc044692cc10477b03b5e3935ae3b57ff7d Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 1 Nov 2024 14:15:02 +0000 Subject: [PATCH 05/10] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- .markdownlint.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 8dca0820..751b8184 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,3 +1,3 @@ --- MD013: false -MD033: false # no-inline-html +MD033: false # no-inline-html From 9213fed280959eb3aece71ee174bc5d991a094ef Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 4 Nov 2024 12:47:29 +0000 Subject: [PATCH 06/10] =?UTF-8?q?Remove=20"pedagogical"=20and=20"geared=20?= =?UTF-8?q?towards"=20=E2=86=92=20"aimed=20at"?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-authored-by: David Stansby --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9af79bcd..805e2af3 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Python packages with our recommended tooling set up and ready to go. ## Tutorial Some quick instructions for using our template are below. -We also have a pedagogical [tutorial](./tutorial.md) that has been given in a couple of workshops geared towards researchers at UCL. +We also have a [tutorial](./tutorial.md) that has been presented in a couple of workshops aimed at researchers at UCL. ## Using our template From 6816c2e03d12b495c8c5410b12d4d2fa560beb67 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 4 Nov 2024 12:53:46 +0000 Subject: [PATCH 07/10] Don't give instructions on installing cookiecutter. Direct to cookiecutter's instructions. --- README.md | 7 +------ 1 file changed, 1 insertion(+), 6 deletions(-) diff --git a/README.md b/README.md index 805e2af3..53c443a3 100644 --- a/README.md +++ b/README.md @@ -32,13 +32,8 @@ If you have [uv] installed, you can use our template with the following one-line uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest ``` -Alternatively you can [install cookiecutter]. +Alternatively you can [install cookiecutter] (following the recommended instructions). Do this if you don't use [uv], or if you're likely to want to use cookiecutter again. -Here's the way we install it: - -```sh -uv tool install cookiecutter -``` Then you'll need to run cookiecutter with our template: From 70fdc49abe0166e112a472e98ae8c36cdd906198 Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 4 Nov 2024 13:03:10 +0000 Subject: [PATCH 08/10] Remove hidden sections for DRY. --- README.md | 90 +++---------------------------------------------------- 1 file changed, 4 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index 53c443a3..ede37ea6 100644 --- a/README.md +++ b/README.md @@ -45,97 +45,15 @@ When [cookiecutter] runs, it will ask you a series of questions to configure you Type the answer or hit return without typing anything to use the default option (shown in parenthesis). At the end, it will print some more follow-up information in the terminal for things like creating a remote repository and making a website for your package. -Here's an example run through - -
Click to expand... - -```sh -uvx cookiecutter gh:ucl-arc/python-tooling --checkout latest - [1/14] Given name(s) of package author (Eva Lu): Grace - [2/14] Family name(s) of package author (Ator): Hopper - [3/14] Email address for package author - will be part of package metadata -(grace.hopper@ucl.ac.uk): - [4/14] Name of project - may contain spaces (Python Template): Example Research Software Project - [5/14] 'Slugified' project name for use in URLs - dash-case recommended -(example-research-software-project): - [6/14] Name for Python package - snake_case recommended -(example_research_software_project): ersp - [7/14] Short description of the project (A cookiecutter package with UCL ARC -recommendations.): An example project. - [8/14] Initialise project directory as a Git repository? [y/n] (y): y - [9/14] Automatically deploy HTML docs to GitHub Pages on pushes to main? [y/n] -(y): y - [10/14] GitHub user or organization name which will be owner of repository -(grace-hopper): UCL-ARC - [11/14] Minimum Python version supported by package - 1 - 3.11 - 2 - 3.12 - 3 - 3.13 - Choose from [1/2/3] (1): - [12/14] Maximum Python version supported by package - 1 - 3.13 - 2 - 3.12 - 3 - 3.11 - Choose from [1/2/3] (1): - [13/14] Which open-source license to release package under - 1 - MIT - 2 - BSD-3 - 3 - GPL-3.0 - Choose from [1/2/3] (1): 1 - [14/14] Organisation(s) to acknowledge for funding of project (optional) (): -Initialized empty Git repository in /Users/scnlf/example-research-software-project/.git/ -GitHub CLI detected, you can create a repo with the following: - -gh repo create UCL-ARC/example-research-software-project -d "An example project." --public -r origin --source example-research-software-project - -The 'Documentation' GitHub Actions workflow has been set up to push the built HTML documentation to a branch gh-pages on pushes to main for deploying as a GitHub Pages website. To allow the GitHub Actions bot to push to the gh-pages branch you need to enable 'Read and write permissions' under 'Workflow permissions' at - -https://github.com/UCL-ARC/example-research-software-project/settings/actions - -After the 'Documentation' workflow has successfully completed at least once you will also need to configure the repository to deploy a GitHub pages site from the content on the gh-pages branch by going to - -https://github.com/UCL-ARC/example-research-software-project/settings/pages - -and under 'Built and deployment' selecting 'Deploy from a branch' for the 'Source' drop-down and 'gh-pages' for the 'Branch' drop-down, leaving the branch path drop-down with its default value of '/ (root)'. -``` - -
- -
- -This will create a project directory structure. - -
Click to expand... +It will have created a directory for your project. +You can see the structure with the `tree` command. +In our example we've called our project `example-research-software-project`: ```sh +ls -ltr | tail -n1 # Shows the last directory that was created tree example-research-software-project -example-research-software-project -├── CITATION.cff -├── LICENSE.md -├── README.md -├── docs -│   ├── LICENSE.md -│   ├── api.md -│   └── index.md -├── mkdocs.yml -├── pyproject.toml -├── schemas -│   └── github-issue-forms.json -├── src -│   └── ersp -│   └── __init__.py -└── tests - └── test_dummy.py - -6 directories, 11 files ``` -
- -
- - - To work on your project, initialise a `git` repository and _install_ your new package editable mode. You probably want to do this in a [virtual environment](./docs/pages/virtual.md). The comments show how to do this in [uv] with `uv venv`: From de3b099841ccb05e9f8e8ceba24f906616c1de2e Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 4 Nov 2024 14:17:49 +0000 Subject: [PATCH 09/10] Consistent link style. --- CONTRIBUTING.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67f3aabd..5b5e5cdc 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,7 +20,7 @@ To contribute a change, please: 1. Create a new branch (or fork if you're not in [@UCL-ARC/collaborations]). 2. Modify an existing page, create a new one, or tweak the template. a. Run - [pre-commit](https://pre-commit.com) which will lint your changes. b. Check + [pre-commit] which will lint your changes. b. Check the tests pass if you modified the template (`pytest -s`). 3. Open a _pull request_ (PR) with changes. 4. Ask someone who did not contribute to the PR from [@UCL-ARC/collaborations] @@ -31,7 +31,7 @@ To contribute a change, please: ### Developing the cookiecutter template -We quite like installing cookiecutter as a [uv tool](https://docs.astral.sh/uv/guides/tools/), so it's available globally: +We quite like installing cookiecutter as a [uv tool], so it's available globally: ```sh uv tool install cookiecutter @@ -55,9 +55,7 @@ branch you want to test. ### Developing the recommended tooling pages -Pages all live in the -`docs/pages` -sub-directory, and are written in markdown. +Pages all live in the `docs/pages` sub-directory, and are written in markdown. To build the webpage locally (for testing) @@ -79,7 +77,9 @@ See the [jekyll docs] for more info. [open an issue]: https://github.com/UCL-ARC/python-tooling/issues/new/choose [Discussions tab]: https://github.com/UCL-ARC/python-tooling/discussions [Research software engineers]: https://society-rse.org/about/history +[pre-commit]: https://pre-commit.com [@UCL-ARC/collaborations]: https://github.com/orgs/UCL-ARC/teams/collaborations +[uv tool]: https://docs.astral.sh/uv/guides/tools [Install jekyll]: https://jekyllrb.com/docs/installation [jekyll docs]: https://jekyllrb.com/docs From c3dabc9946aa4e55dac634eb2a69f9c00b82d41d Mon Sep 17 00:00:00 2001 From: Sam Cunliffe Date: Mon, 4 Nov 2024 14:19:40 +0000 Subject: [PATCH 10/10] Add more comments to markdownlint.yaml. --- .markdownlint.yaml | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 751b8184..c2a93fce 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,3 +1,4 @@ --- -MD013: false +# Markdown linting rules to ignore. +MD013: false # line-length MD033: false # no-inline-html