scientificcomputing · jorgensd · Sep 23, 2022 · Sep 20, 2022 · Sep 22, 2022
diff --git a/README.md b/README.md
@@ -2,6 +2,8 @@
 
 This repository is a template for how to set up a reproducible python environment with GitHub.
 
+The documentation for this repository can be found [here](https://jorgensd.github.io/reproducibility/).
+
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jorgensd/reproducibility/gh-pages?labpath=_sources)
 [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://jorgensd.github.io/reproducibility)
 [![MIT License](https://img.shields.io/github/license/jorgensd/reproducibility)](LICENSE)

diff --git a/demo/demo.py b/demo/demo.py
@@ -1,6 +1,5 @@
 # + [markdown]
 # # An introduction to the light format
-#
 # Author: Jørgen S. Dokken
 #
 # SPDX-License-Identifier:    MIT

diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -1,12 +1,39 @@
 format: jb-book
 root: index
 
-chapters:
-  - file: "badges"
-  - file: "packaging"
-  - file: "github"
-  - file: "publishing"
- # This file does not exist in the Github repository
- # It should be copied here by adding it in the `Makefile`
-  - file: "demo"
-  - file: "api"
+parts:
+  - caption: Python packaging
+    chapters:
+    - file: "part1/packaging"
+    - file: "part1/coverage"
+    - file: "part1/linting"
+    - file: "part1/typing"
+    - file: "part1/testing"
+
+  - caption: Github tools
+    chapters:
+    - file: "part2/github"
+    - file: "part2/workflows"
+    - file: "part2/citeable"
+    - file: "part2/issues"
+
+  - caption: Jupyter-book
+    chapters:
+    - file: "part3/publishing"
+
+  - caption: Creating a Package API
+    chapters:
+    - file: "part3/auto_api"
+    - file: "api"
+
+  - caption: Demos
+    chapters:
+    - file: part3/auto_demos
+    # The following file should be autogenerated by the Makefile
+    - file: "demo.ipynb"
+
+  - caption: Other Features
+    chapters:
+    - file: "part4/badges"
+
+
diff --git a/docs/part1/coverage.md b/docs/part1/coverage.md
@@ -0,0 +1 @@
+# Coverage reports
diff --git a/docs/part1/linting.md b/docs/part1/linting.md
@@ -0,0 +1 @@
+# Python formatting
diff --git a/docs/packaging.md → docs/part1/packaging.md b/docs/packaging.md → docs/part1/packaging.md
@@ -1,15 +1,7 @@
-# Python-packaging
+# Create an installable package
 
 To be able to create a python package, we need a folder with the name of the package (in this repository it is called `mypackage`, located under `src/mypackage`), and a `pyproject.toml` file.
 
 
 ## Pyproject.toml
 
-
-## Coverage reports
-
-
-## Python linting (flake8)
-
-
-## Python typing (mypy)
diff --git a/docs/part1/testing.md b/docs/part1/testing.md
@@ -0,0 +1 @@
+# Testing
diff --git a/docs/part1/typing.md b/docs/part1/typing.md
@@ -0,0 +1 @@
+# Python typing
diff --git a/docs/github.md → docs/part2/citeable.md b/docs/github.md → docs/part2/citeable.md
@@ -1,18 +1,4 @@
-# Github tools
-
-## Issue template
-See [Adding an issue template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) for more information.
-
-
-## Workflows
-
-
-### Uploading artifacts
-
-### Publishing to Pages
-
-
-## Make a repository citable
+# Make a repository citable
 The easiest way to make your repository citable is to add a `CITATION.cff` file to the repository, as it is supported by both 
 [Zenodo's](https://zenodo.org/) and it's [Github integration](https://docs.github.com/en/repositories/archiving-a-github-repository/referencing-and-citing-content) and [Github](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files) itself.
 
diff --git a/docs/part2/github.md b/docs/part2/github.md
@@ -0,0 +1,2 @@
+# Github tools
+
diff --git a/docs/part2/issues.md b/docs/part2/issues.md
@@ -0,0 +1,4 @@
+# Issue template
+See [Adding an issue template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) for more information.
+
+
diff --git a/docs/part2/workflows.md b/docs/part2/workflows.md
@@ -0,0 +1,5 @@
+# Workflows
+
+## Uploading artifacts
+
+## Publishing to Pages
diff --git a/docs/part3/auto_api.md b/docs/part3/auto_api.md
@@ -0,0 +1 @@
+# Auto-generation
diff --git a/docs/part3/auto_demos.md b/docs/part3/auto_demos.md
@@ -0,0 +1,17 @@
+As shown in [Publishing a Jupyter book](publishing), we can add `.ipynb` files to the Jupyter book. This is achieved by adding their relative path with respect to `index.md` to `_toc.yml`.
+
+These files can either be generated by hand, and added to the `docs` or auto-generated from a `.py` file, using `jupytext`.
+
+The command
+```bash
+jupytext --to=ipynb --set-kernel=python3 path/to/demo.py --output=path/to/docs.ipynb
+```
+generates a notebook compatible with *Jupyter Book*.
+
+The Python file should follow the conventions of the [light format](https://jupytext.readthedocs.io/en/latest/formats.html#the-light-format) for appropriate rendering.
+
+This is illustrated in the following auto-converted demo.
+
+# Auto-conversion of demos
+
+In the [Makefile](https://github.com/jorgensd/reproducibility/blob/main/Makefile) one can find the instructions for auto-converting the demos and building the book.
diff --git a/docs/part3/publishing.md b/docs/part3/publishing.md
@@ -0,0 +1,8 @@
+# Building a book
+
+## File formats
+
+## `_toc.yml`
+
+## `_config.yml` 
+
diff --git a/docs/badges.md → docs/part4/badges.md b/docs/badges.md → docs/part4/badges.md
diff --git a/docs/publishing.md b/docs/publishing.md
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,4 @@
		# Issue template
		See [Adding an issue template](https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests/configuring-issue-templates-for-your-repository) for more information.