You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Just before I forget: a few minor/trivial things we discussed in person
but that I didn't make a ticket for 🤦.
I also did a bit of a review of the text in the website's index.html.
Mainly adding a mention of our template amongst the discussion of "use
the community templates". It's a bit WET from the packaging page, but
there's already a bit of duplication there and it's all probably sane
from the point of view of a reader.
I spotted a line that should have gone with #271 and a post-merging
comment on #264.
---------
Co-authored-by: Matt Graham <matthew.m.graham@gmail.com>
Copy file name to clipboardexpand all lines: docs/index.md
+35-16
Original file line number
Diff line number
Diff line change
@@ -4,30 +4,49 @@ layout: home
4
4
nav_order: 1
5
5
---
6
6
7
-
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).
7
+
This site documents common tooling we use in research software Python projects
8
+
at the [Centre for Advanced Research Computing](https://www.ucl.ac.uk/arc/)
9
+
(ARC) at [UCL](https://www.ucl.ac.uk).
8
10
9
-
It is not comprehensive, but intended as a forum to share knowledge across projects.
10
-
Each page contains a table of packages or services that are useful when building a Python package.
11
+
These pages started as a forum to share knowledge across projects and have now
12
+
grown into a list of our default recommendations. Each page contains a table of
13
+
packages, tools, or services that are useful when building a Python package.
11
14
Each entry has
12
15
13
-
- a link to the package or service
14
-
- a short summary of what it does
15
-
- traffic lights
16
-
- a link to a package developed by someone in ARC that uses it
16
+
- a link to the package or service,
17
+
- a short summary of what it does,
18
+
- and traffic light!
17
19
18
20
## Choosing tools
19
21
20
-
If you are working within a larger community, always start with the same tools they recommend.
21
-
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.
22
-
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.
23
-
24
-
Otherwise, each page on this site highlights recommended packages or services for each area.
25
-
These should not be taken as set in stone for every project, but are a good place to start.
22
+
If you are working within a larger community, always start with the same tools
23
+
they recommend. For example, the [napari](https://napari.org/) community have a
[SciKit-Surgery](https://scikit-surgery.github.io/scikit-surgery/) community
27
+
have [PythonTemplate](https://github.com/SciKit-Surgery/PythonTemplate), both
28
+
used to create new Python-based libraries. Using common tooling and structure
29
+
makes it easier for others in the community to contribute to your package. Once
30
+
_you_ get used to the structure makes it easier for you to contribute back to
31
+
other packages.
32
+
33
+
🍪 If you just want to get started with our recommendations, we have our own
34
+
[template](https://github.com/UCL-ARC/python-tooling#using-this-template) that
35
+
lives in the same repository as these pages.
36
+
37
+
Otherwise, each page on this site highlights recommended packages or services
38
+
for each area. These should not be taken as set in stone for every project, but
39
+
are a good place to start.
26
40
27
41
### Traffic lights
28
42
29
43
Each item has an (opinionated) traffic light. The meaning of these is:
30
44
31
-
- 🟢 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.
32
-
- 🟠 We don't discourage using this, but it may duplicate functionality of a green tool.
33
-
- 🔴 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.
45
+
- 🟢 At least one person in ARC uses this. We actively recommend using it above
46
+
other tools. It is the single recommended tool for a given purpose.
47
+
- 🟠 We don't discourage using this, but it may duplicate functionality of a
48
+
green tool.
49
+
- 🔴 We actively discourage using this. This could be because it's no longer
50
+
maintained, not open source, or difficult to use. Consider moving to
51
+
alternatives if you're currently using something that's red. A reason for not
|[binder](https://mybinder.org/)| Turns a Git repository into a collection of interactive notebooks | 🟢 |
17
-
|[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. | 🟢 |
18
-
|[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)| 🟠 |
|[binder](https://mybinder.org/)| Turns a Git repository into a collection of interactive notebooks | 🟢 |
17
+
|[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. | 🟢 |
18
+
|[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)| 🟠 |
|[pytest](https://docs.pytest.org/en/stable/contents.html)| A framework for writing and running tests. | 🟢 |
13
-
|[tox](https://tox.wiki/en/latest/index.html)| A framework that allows running tests and packaging in different environments. | 🟢 |
14
-
|[unittest](https://docs.python.org/dev/library/unittest.html#module-unittest)| A framework built in to Python for writing and running tests. | 🟠 |
15
-
16
-
<details>
17
-
<summary>🟢 explanation</summary>
18
-
We recommend `pytest` over `unittest` because `pytest` tends to encourage a cleaner style, there are also extensive plugins and it's in widespread use.
|[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. | 🟢 |
13
+
|[tox](https://tox.wiki/en/latest/index.html)| A framework that allows running tests and packaging in different environments. | 🟢 |
14
+
|[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. | 🟠 |
0 commit comments