diff --git a/.markdownlint.yaml b/.markdownlint.yaml index 02907b2b..c2a93fce 100644 --- a/.markdownlint.yaml +++ b/.markdownlint.yaml @@ -1,2 +1,4 @@ --- -MD013: false +# Markdown linting rules to ignore. +MD013: false # line-length +MD033: false # no-inline-html diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 179da725..052f554b 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -26,7 +26,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] @@ -35,6 +35,46 @@ To contribute a change, please: 6. If changes are requested, the PR author should address the comments, and then ask for review again. +### Developing the cookiecutter template + +We quite like installing cookiecutter as a [uv tool], so it's available globally: + +```sh +uv tool install cookiecutter +``` + +To run cookiecutter using a specific branch of the template: + +```sh +cookiecutter gh:UCL-ARC/python-tooling --checkout +``` + +If you have this repo locally (presumably the case if you're developing), you +can instead run the following: + +```sh +cookiecutter /path/to/your/checkout/of/python-tooling --checkout +``` + +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` sub-directory, and are written in markdown. + +To build the webpage locally (for testing) + +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. + 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] for more info. + @@ -43,5 +83,9 @@ To contribute a change, please: [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 diff --git a/README.md b/README.md index fa5a2a69..ede37ea6 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - +
UCL ARC Python tooling logo

UCL ARC Python Recommendations

@@ -19,12 +19,61 @@ 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 [tutorial](./tutorial.md) that has been presented in a couple of workshops aimed at 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 +``` + +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. + +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. + +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 +``` + +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 +117,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. - -