diff --git a/docs/index.md b/docs/index.md index 16dfe2e3..a8b3ac07 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 tool 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. diff --git a/docs/pages/jupyter-notebooks.md b/docs/pages/jupyter-notebooks.md index 565ce4f0..6329dbaf 100644 --- a/docs/pages/jupyter-notebooks.md +++ b/docs/pages/jupyter-notebooks.md @@ -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 diff --git a/docs/pages/templates.md b/docs/pages/templates.md index 6b1061e5..30edc6f0 100644 --- a/docs/pages/templates.md +++ b/docs/pages/templates.md @@ -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 | | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ | @@ -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 | 🚦 | | ----------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | :-: | diff --git a/docs/pages/testing.md b/docs/pages/testing.md index 8cc5dcce..30e2d54a 100644 --- a/docs/pages/testing.md +++ b/docs/pages/testing.md @@ -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. | 🟠 | - -
-🟢 explanation -We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use. -
+| 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