From 3a5efea7f21347a6e54619bec67a7a91b5e60899 Mon Sep 17 00:00:00 2001 From: Jeff Jennings Date: Fri, 27 Sep 2024 14:24:30 -0400 Subject: [PATCH 1/2] contribution guidelines: add guidance on requirements file and associated notebook cell --- src/contributing/contributing.md | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/src/contributing/contributing.md b/src/contributing/contributing.md index d1780ab..e3c4b82 100644 --- a/src/contributing/contributing.md +++ b/src/contributing/contributing.md @@ -5,7 +5,7 @@ slug: '/contributing/how-to-contribute' ## Overview -Each tutorial is a [Jupyter notebook](https://jupyter.org/) file. Each notebook is saved in a separate directory within the `tutorials/notebooks` subdirectory in this project. For an example, let's look at the source notebook of the [FITS-header](https://github.com/astropy/astropy-tutorials/tree/main/tutorials/FITS-header/) tutorial. Within `tutorials/notebooks/FITS-header`, there is a single Jupyter notebook file that contains the text and code for the tutorial, and any small data files used in the tutorial (in this case, a single FITS file). The notebook file is automatically run and converted into a static HTML page ([for example](https://learn.astropy.org/tutorials/FITS-header.html)), which is then displayed in the tutorial listing on the main tutorials webpage, http://tutorials.astropy.org. Each tutorial notebook file also contains information such as the author's name, month and year it was written, and any other metadata that should be associated with the tutorial. +Each tutorial is a [Jupyter notebook](https://jupyter.org/) file. Each notebook is saved in a separate directory within the `tutorials/notebooks` subdirectory in this project. For an example, let's look at the source notebook of the [FITS-header](https://github.com/astropy/astropy-tutorials/tree/main/tutorials/FITS-header/) tutorial. Within `tutorials/notebooks/FITS-header`, there is a single Jupyter notebook file that contains the text and code for the tutorial, any small data files used in the tutorial (in this case, a single FITS file), and a `requirements.txt` file that specifies the required packages to run notebooks in `tutorials/notebooks/FITS-header`. The notebook file is automatically run and converted into a static HTML page ([for example](https://learn.astropy.org/tutorials/FITS-header.html)), which is then displayed in the tutorial listing on the main tutorials webpage, http://tutorials.astropy.org. Each tutorial notebook file also contains information such as the author's name, month and year it was written, and any other metadata that should be associated with the tutorial. ## Content Guidelines @@ -20,7 +20,7 @@ Each tutorial is a [Jupyter notebook](https://jupyter.org/) file. Each notebook ### Template intro -The first cell in every tutorial notebook is used for the title, author list, keywords, and summary and should adhere to the following format: +The first cell in every tutorial notebook is a markdown cell used for the title, author list, keywords, and summary. It should adhere to the following format: ``` # Title name @@ -44,6 +44,13 @@ In this tutorial, we will download a data file, do something to it, and then visualize it. ``` +The second cell in every tutorial notebook is a code cell used to display required packages for users, and should be the following lines (this expects the `requirements.txt` file in the notebook's directory with a list of required packages to be present): + +``` +with open('requirements.txt') as f: + print(f"Required packages for this notebook:\n{f.read()}") +``` + ### Code - Demonstrate good commenting practice From 8af29e2b335322ec8741fa050485f15ad4f9dcee Mon Sep 17 00:00:00 2001 From: Jeff Jennings Date: Wed, 9 Oct 2024 10:39:47 -0400 Subject: [PATCH 2/2] update contributing text --- src/contributing/contributing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/contributing/contributing.md b/src/contributing/contributing.md index e3c4b82..f20f1e7 100644 --- a/src/contributing/contributing.md +++ b/src/contributing/contributing.md @@ -20,7 +20,7 @@ Each tutorial is a [Jupyter notebook](https://jupyter.org/) file. Each notebook ### Template intro -The first cell in every tutorial notebook is a markdown cell used for the title, author list, keywords, and summary. It should adhere to the following format: +The first cell in every tutorial notebook is a markdown cell used for the title, author list, keywords, and summary. All of this information should be contained in a single cell and should adhere to the following format: ``` # Title name @@ -44,7 +44,7 @@ In this tutorial, we will download a data file, do something to it, and then visualize it. ``` -The second cell in every tutorial notebook is a code cell used to display required packages for users, and should be the following lines (this expects the `requirements.txt` file in the notebook's directory with a list of required packages to be present): +The second cell in every tutorial notebook is a code cell used to display required packages for users, and should be the following lines (this expects the `requirements.txt` file to be present in the notebook's directory): ``` with open('requirements.txt') as f: