Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Leftovers. #282

Merged
merged 2 commits into from
Jan 24, 2024
Merged

Leftovers. #282

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
b13782f
Leftovers.
samcunliffe Jan 24, 2024
2d8a78d
Matt's fixes.
samcunliffe Jan 24, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
51 changes: 35 additions & 16 deletions docs/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,30 +4,49 @@ layout: home
nav_order: 1
---

This site documents common tooling we use in Python projects at the [Advanced Research Computing center](https://www.ucl.ac.uk/arc/) (ARC) at [UCL](https://www.ucl.ac.uk).
This site documents common tooling we use in research software python projects
at the [Centre for Advanced Research Computing](https://www.ucl.ac.uk/arc/)
(ARC) at [UCL](https://www.ucl.ac.uk).

It is not comprehensive, but intended as a forum to share knowledge across projects.
Each page contains a table of packages or services that are useful when building a Python package.
These pages started as a forum to share knowledge across projects and have now
grown into a list of our default recommendations. Each page contains a table of
packages, tools, or services that are useful when building a Python package.
Each entry has

- a link to the package or service
- a short summary of what it does
- traffic lights
- a link to a package developed by someone in ARC that uses it
- a link to the package or service,
- a short summary of what it does,
- and traffic light!

## Choosing tools

If you are working within a larger community, always start with the same tools they recommend.
For example, the [`napari`](https://napari.org/) community have [`cookiecutter-napari-plugin`](https://github.com/napari/cookiecutter-napari-plugin) and the [SciKit-Surgery](https://scikit-surgery.github.io/scikit-surgery/) community have [PythonTemplate](https://github.com/SciKit-Surgery/PythonTemplate), both used to create new Python-based libraries.
This makes it easier for others in the community to contribute to your package, and once you get used to the structure makes it easier for you to contribute back to other packages.

Otherwise, each page on this site highlights recommended packages or services for each area.
These should not be taken as set in stone for every project, but are a good place to start.
If you are working within a larger community, always start with the same tools
they recommend. For example, the [napari](https://napari.org/) community have a
[`cookiecutter-napari-plugin`](https://github.com/napari/cookiecutter-napari-plugin)
template and the
[SciKit-Surgery](https://scikit-surgery.github.io/scikit-surgery/) community
have [PythonTemplate](https://github.com/SciKit-Surgery/PythonTemplate), both
used to create new Python-based libraries. Using common tooling and structure
makes it easier for others in the community to contribute to your package. Once
_you_ get used to the structure makes it easier for you to contribute back to
other packages.

🍪 If you just want to get started with our recommendations, we have our own
[template](https://github.com/UCL-ARC/python-tooling#using-this-template) that
lives in the same repository as these pages.

Otherwise, each page on this site highlights recommended packages or services
for each area. These should not be taken as set in stone for every project, but
are a good place to start.

### Traffic lights

Each item has an (opinionated) traffic light. The meaning of these is:

- 🟢 At least one person in ARC uses this. We actively recommend using it above other tools. It is the single recommended package for a given purpose.
- 🟠 We don't discourage using this, but it may duplicate functionality of a green tool.
- 🔴 We actively discourage using this. This could be because it's no longer maintained, not open source, or difficult to use. Consider moving to alternatives if you're currently using something that's red. A reason for not using this is given.
- 🟢 At least one person in ARC uses this. We actively recommend using it above
other tools. It is the single recommended package for a given purpose.
- 🟠 We don't discourage using this, but it may duplicate functionality of a
green tool.
- 🔴 We actively discourage using this. This could be because it's no longer
maintained, not open source, or difficult to use. Consider moving to
alternatives if you're currently using something that's red. A reason for not
using this is given.
10 changes: 5 additions & 5 deletions docs/pages/jupyter-notebooks.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,11 @@ Notebooks can also be a valid alternative to Python scripts for running and reco

## Live executable environments

| Name | Short description | 🚦 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
| [binder](https://mybinder.org/) | Turns a Git repository into a collection of interactive notebooks | 🟢 |
| [Google Colab](https://colab.google/) | Colab is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs. | 🟢 |
| [GitHub codespace with JupyterLab](https://docs.github.com/en/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning#opening-your-codespace-in-jupyterlab) | A codespace is a development environment that is hosted in the cloud and can run [Python and Jupyter notebooks](https://github.com/github/codespaces-jupyter) | 🟠 |
| Name | Short description | 🚦 |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
| [binder](https://mybinder.org/) | Turns a Git repository into a collection of interactive notebooks | 🟢 |
| [Google Colab](https://colab.google/) | Colab is a hosted Jupyter Notebook service that requires no setup to use and provides free access to computing resources, including GPUs and TPUs. | 🟢 |
| [GitHub codespaces with JupyterLab](https://docs.github.com/en/codespaces/developing-in-a-codespace/getting-started-with-github-codespaces-for-machine-learning#opening-your-codespace-in-jupyterlab) | A codespace is a development environment that is hosted in the cloud and can run [Python and Jupyter notebooks](https://github.com/github/codespaces-jupyter) | 🟠 |

## Linting

Expand Down
19 changes: 11 additions & 8 deletions docs/pages/templates.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,23 @@ layout: default
nav_order: 2
---

⚠️ This page is still under construction! ⚠️

# Package templates

## Recommended ARC template

This [UCL-ARC/python-tooling](https://github.com/UCL-ARC/python-tooling) repository contains our recommended package template for new ARC projects.
It pre-configures the recommended tools listed in the other pages of this site.
If you're making a package within one of the communities listed below, we recommend using their template instead.
The [UCL-ARC/python-tooling](https://github.com/UCL-ARC/python-tooling)
repository contains our recommended package template for new ARC projects. It
pre-configures the recommended tools listed in the other pages of this site. If
you are working on a new project, our template should be a good starting point!

If you're making a package for a community that already has a template in
general use (some examples are listed below) we recommend using their template
instead.

## Domain specific templates

These templates are used by specific communities.
If you're making a package within one of these communities, we recommend using their package template.
These templates are used by specific communities. If you're making a package
within one of these communities, we recommend using their package template.

| Name | Short description |
| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
Expand All @@ -27,7 +30,7 @@ If you're making a package within one of these communities, we recommend using t

## Template engines

These are packages that can be used for creating your own package template.
These are tools that can be used for creating your own package template.

| Name | Short description | 🚦 |
| ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | :-: |
Expand Down
15 changes: 5 additions & 10 deletions docs/pages/testing.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,16 +7,11 @@ layout: default

## Test runners

| Name | Short description | 🚦 |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | :-: |
| [pytest](https://docs.pytest.org/en/stable/contents.html) | A framework for writing and running tests. | 🟢 |
| [tox](https://tox.wiki/en/latest/index.html) | A framework that allows running tests and packaging in different environments. | 🟢 |
| [unittest](https://docs.python.org/dev/library/unittest.html#module-unittest) | A framework built in to Python for writing and running tests. | 🟠 |

<details>
<summary>🟢 explanation</summary>
We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use.
</details>
| Name | Short description | 🚦 |
| ----------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :-: |
| [pytest](https://docs.pytest.org/en/stable/contents.html) | A framework for writing and running tests. We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use. | 🟢 |
| [tox](https://tox.wiki/en/latest/index.html) | A framework that allows running tests and packaging in different environments. | 🟢 |
| [unittest](https://docs.python.org/dev/library/unittest.html#module-unittest) | Python's built in framework for writing and running tests. Encourages use of classes as test fixtures. | 🟠 |

## pytest plugins

Expand Down
Loading