Updating contributions and infrastructure pages

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` 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/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.
 
 ## Content Guidelines
 
@@ -98,7 +98,7 @@ When the tutorial is ready to be incorporated, Learn Astropy maintainers will op
 
 ### Method Two: Submit a Pull Request
 
-The process for contributing a tutorial involves the [GitHub fork](https://help.github.com/articles/working-with-forks/) and `git` workflow concepts [branch, push, pull request](https://help.github.com/articles/proposing -changes-to-your-work-with-pull-requests/).
+The process for contributing a tutorial involves the [GitHub fork](https://help.github.com/articles/working-with-forks/) and `git` workflow concepts [branch, push, pull request](https://help.github.com/articles/proposing-changes-to-your-work-with-pull-requests/).
 
 To contribute a new tutorial, first fork the `astropy-tutorials` repository. Then, clone your fork locally to your machine (replace `<GITHUB USERNAME>` with your GitHub username):
 
@@ -112,10 +112,10 @@ Next, create a branch in your local repository with the name of the tutorial you
 git checkout -b Spectral-Line-Fitting
 ```
 
-The notebook files must be written as a single Jupyter notebook in a directory within the `tutorials/notebooks` directory. The name of the notebook must be the same as the subdirectory name. We'll create a new directory in `tutorials/notebooks` with the same name as the branch:
+The notebook files must be written as a single Jupyter notebook in a directory within the `tutorials` directory. The name of the notebook must be the same as the subdirectory name. We'll create a new directory in `tutorials` with the same name as the branch:
 
 ```
-mkdir tutorials/notebooks/Spectral-Line-Fitting
+mkdir tutorials/Spectral-Line-Fitting
 ```
 
 All files used by the tutorial -- e.g., example data files, the Jupyter notebook file itself -- should go in this directory.
@@ -127,7 +127,19 @@ scipy==1.0
 numpy>=1.13
 ```
 
-To see an example, have a look at the FITS-header [requirements.txt file](https: //github.com/astropy/astropy-tutorials/blob/master/tutorials/notebooks/FITS-head er/requirements.txt).
+To see an example, have a look at the FITS-header [requirements.txt file](https://github.com/astropy/astropy-tutorials/blob/main/tutorials/FITS-header/requirements.txt).
+
+When you commit your notebook to the git repository five tests will automatically run:
+
+```
+trim trailing whitespace
+fix end of files
+check yaml
+check for added large files
+nbstripout
+```
+
+If any of them fail, your files will be automatically modified in accordance with the issues, and the commit will not proceed. If you run `git status` you will see there are unstages changes. Now `git add` the changed files and rerun the commit command. All the test should now pass and the commit complete. 
 
 Push the notebook and other files from your local branch up to your fork of the repository on GitHub (by default, named 'origin'):
 

src/contributing/infrastructure.md

@@ -5,72 +5,62 @@ slug: '/contributing/infrastructure'
 
 ## Overview
 
-Tutorials are written as Jupyter notebooks on the `master` branch of the `astropy/astropy-tutorials` repository in `tutorials/notebooks/`. These notebook files do not contain output in order to simplify version-controlling the files.
+Tutorials are written as Jupyter notebooks on the `master` branch of the `astropy/astropy-tutorials` repository in `tutorials/`. These notebook files do not contain output in order to simplify version-controlling the files.
 
 The rendered Astropy-tutorials site is built using Sphinx with the Astropy theme to look like the main documentation. Sphinx requires restructured text (RST) files for its build process, so use an intermediate step to run the notebooks to produce output, and then convert the notebook files into RST files.
 
 We use [CircleCI](https://circleci.com) to do the Sphinx build, which is then pushed to the `gh-pages` branch of the repository and served by GitHub. The notebooks are first converted to RST files during the Sphinx build by doing the conversion at the end of the [Sphinx configuration file](https://github.com/astropy/astropy-tutorials/blob/master/tutorials/conf.py).
 
 ## Why not use nbsphinx?
 
-Both running and converting the notebooks is handled automatically by the Sphinx plugin `nbsphinx`, but it doesn't support all of the features we want. In particular, there is no supported way to modify the template file that controls the output RST file that gets generated from each notebook; we want to be able to modify the template so we can add the links mentioned above.
+Both running and converting the notebooks is handled automatically by the Sphinx plugin `nbsphinx`, but it doesn't support all of the features we want. In particular, there is no supported way to modify the template file that controls the output RST file that gets generated from each notebook.
 
 ## Tutorials directory structure
 
-The notebook files must be written as a single Jupyter notebook in a directory within the `tutorials/notebooks` directory. The name of the notebook must be the same as the subdirectory name. This is just needed for auto-generating links to the source notebooks from the generated RST pages.
+The notebook files must be written as a single Jupyter notebook in a directory within the `tutorials` directory. The name of the notebook must be the same as the subdirectory name. This is needed for auto-generating links to the source notebooks from the generated RST pages.
 
 ## Testing notebook execution
 
-You can use the custom nbconvert script in the astropy-tutorials repository to test that the tutorials all execute correctly. From the top-level repository path:
+There are notebook excecution commands in the [Makefile](https://github.com/astropy/astropy-tutorials/blob/master/Makefile). From the root level of the cloned or downloaded repository:
 
 ```
-python scripts/convert.py tutorials/notebooks -v --exec-only
+make execute
 ```
 
-Running the convert script with the flag `--exec-only` will just execute the notebooks and won't generate RST files. If you have already run the notebooks once, you may need to also specify the `-o` or `--overwrite` flag: by default, the script will only execute notebooks that haven't already been executed. The `-v` flag just tells the script to output more "verbose" messages, which you may or may not want.
+to only execute newly modified notebooks, or
 
-The above command will execute all notebooks in any subdirectory of the `tutorials/notebooks` path. If you want to just execute a single notebook, you can specify the path to a single notebook file, e.g.:
 
 ```
-python scripts/convert.py tutorials/notebooks/coordinates/coordinates.ipynb -v --exec-only
+make executeall
 ```
 
-You can also do this when running and generating RST files, which can be useful when writing a new tutorial to make sure it renders in RST properly. To do this, just remove the `--exec-only` flag:
+to execute all of the notebooks.
+
+The package `GitPython` is required for modified-files-only commands.
+If you are executing all the notebooks `make init` with install all necessary requirements.
 
-```
-python scripts/convert.py tutorials/notebooks/coordinates/coordinates.ipynb -v
-```
 
 ## Building the tutorials page locally
 
+
 For this, you can use the [Makefile](https://github.com/astropy/astropy-tutorials/blob/master/Makefile) at the top-level of the tutorials repository. From the root level of the cloned or downloaded repository:
 
 ```
-make html
+make build
 ```
 
-Will execute and convert the Jupyter notebooks to RST files, then do the Sphinx build. If this returns an error, you may need to initialize the `astropy_helpers` submodule (read the error message). That is, you may need to do:
+Will execute and convert only newly modified the Jupyter notebooks to RST files, then do the Sphinx build.
+To build all notebooks use:
 
 ```
-git submodule init
-git submodule update
-make html
+make buildall
 ```
 
-Once this is done, you will find the index for the pages in your local `build/html/index.html` file.
-
-For testing, you may want to run the build process on just one notebook file, as the full build takes some time to execute and convert all of the tutorial notebooks. To do this, you can set the `NBFILE` environment variable to specify the path to a notebook file relative to the `tutorials` path. For example, to run the build process on just the FITS-header tutorial:
+Once this is done, you will find the index for the pages in your local `_build/index.html` file.
 
-```
-$ NBFILE=notebooks/FITS-header/FITS-header.ipynb make html
-```
-
-If you use multiple environments to manage your python installation, you might be surprised to find that by default this build does _not_ use the same python environment you are running sphinx in. This is because the `nbconvert` machinery depends on Jupyter kernels to create a separate environment to run each notebook. To use a specific environment, you will need to use the `jupyter kernelspec` or `ipykernel install` command to create a named kernel for your favored environment. Then pass it into sphinx using the `NBCONVERT_KERNEL` environment variable. Something like:
+The package `GitPython` is required for modified-files-only commands.
+If you are building all the notebooks `make init` with install all necessary requirements.
 
-```
-$ python -m ipykernel install --user --name astropy-tutorials --display-name "Python (astropy-tutorials)"
-$ NBCONVERT_KERNEL=astropy-tutorials make html
-```
 
 ## Releases