Reorder book (#31)

jorgensd · web-flow · commit 9f973672bb32 · 2022-09-20T15:09:46.000+01:00
* Split book into multiple files.
Decouple from readme
Add notebook as dependency with binder
Add shell structure for new sections

* Add files
diff --git a/Makefile b/Makefile
@@ -1,15 +1,8 @@
-# We want to use the README.md and contributing.md file from this folder 
-# in the Jupter book. These files should be listed in `docs/_toc.yml`
-DOCS = README.md CONTRIBUTING.md
-
 # List of Python demos (without file extenion) from the repo `demo` to include in the jupyterbook. 
 # These files should be listed in `docs/_toc.yml`
 DEMOS = demo
 
 doc: # Generate Sphinx HTML documentation, including API docs 
-	@for file in ${DOCS}; do \
-		cp $$file docs/. ;\
-	done 
 # We use --set-kernel with jupytext to make it possible for binder to pick it up
 	@for demo in ${DEMOS}; do \
 		jupytext --to=ipynb --set-kernel=python3 demo/$$demo.py --output=docs/$$demo.ipynb ;\
diff --git a/README.md b/README.md
@@ -2,52 +2,7 @@
 
 This repository is a template for how to set up a reproducible python environment with GitHub.
 
-## Badges
-
 [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jorgensd/reproducibility/gh-pages?labpath=_sources)
-
-To get the `Launch Binder` badge, go to: [https://mybinder.org/](https://mybinder.org/) and fill in (specifics for this repo in brackets):
-- Your Github repository (https://github.com/jorgensd/reproducibility)
-- Git ref (`gh-pages`, see: [How to create github pages](#ghpages))
-- Path to notebook file (`_sources`, as generated by `jupyter-book`, see [Jupyter-book](#jupyterbook))
-
-Then press `Launch`, and then `Expand to see the text below, paste it into your README to show a binder badge` and copy the markdown code. If you render the README.md file as plaintext, you can see all the settings explicitly in the image link
-
 [![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://jorgensd.github.io/reproducibility)
+[![MIT License](https://img.shields.io/github/license/jorgensd/reproducibility)](LICENSE)
 
-Replace link in image (https://jorgensd.github.io/reproducibility) with your [Github pages url](#ghpages)
-
-![MIT License](https://img.shields.io/github/license/jorgensd/reproducibility)
-
-Replace `username/repo` in image link with appropriate user/respository.
-
-## Python-packaging
-
-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.
-
-
-## 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.
-
-## Adding an 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.
-
-## Contributing
-
-Contributions are always welcome!
-
-See [CONTRIBUTING.md](CONTRIBUTING.md) for ways to get started.
-
-A good idea is to look at the [issue tracker](https://github.com/jorgensd/reproducibility/issues) and see if you can resolve any open issues.  A list of good first issues can be found [here](https://github.com/jorgensd/reproducibility/contribute)
-
-If you find a bug in the source code, please [open an issue](https://github.com/jorgensd/reproducibility/issues/new).
-
-
-## <a id="ghpages"></a> Auto-publish to Github Pages
-
-Add text
-
-## <a id="jupyterbook"></a> Jupyter-book
-
-Add text
diff --git a/docs/_toc.yml b/docs/_toc.yml
@@ -1,7 +1,12 @@
 format: jb-book
-root: README
+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"
-  - file: "CONTRIBUTING"
diff --git a/docs/badges.md b/docs/badges.md
@@ -0,0 +1,21 @@
+# Badges
+
+## Binder
+[![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/jorgensd/reproducibility/gh-pages?labpath=_sources)
+
+To get the `Launch Binder` badge, go to: [https://mybinder.org/](https://mybinder.org/) and fill in (specifics for this repo in brackets):
+- Your Github repository (https://github.com/jorgensd/reproducibility)
+- Git ref (`gh-pages`, see: [How to create github pages](#ghpages))
+- Path to notebook file (`_sources`, as generated by `jupyter-book`, see [Jupyter-book](#jupyterbook))
+
+Then press `Launch`, and then `Expand to see the text below, paste it into your README to show a binder badge` and copy the markdown code. If you render the README.md file as plaintext, you can see all the settings explicitly in the image link
+
+## Jupyter book
+[![Jupyter Book Badge](https://jupyterbook.org/badge.svg)](https://jorgensd.github.io/reproducibility)
+
+Replace link in image (https://jorgensd.github.io/reproducibility) with your [Github pages url](#ghpages)
+
+## Licence
+![MIT License](https://img.shields.io/github/license/jorgensd/reproducibility)
+
+Replace `username/repo` in image link with appropriate user/respository.
diff --git a/docs/github.md b/docs/github.md
@@ -0,0 +1,18 @@
+# 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
+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/index.md b/docs/index.md
@@ -0,0 +1,7 @@
+# Reproducible workflow for researchers
+
+This repository is a template for how to set up a reproducible python environment with GitHub.
+
+## Contents
+```{tableofcontents}
+```
diff --git a/docs/packaging.md b/docs/packaging.md
@@ -0,0 +1,15 @@
+# Python-packaging
+
+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/publishing.md b/docs/publishing.md
@@ -0,0 +1,7 @@
+# Jupyter-book
+
+## Building a minimal book
+
+## Adding Python package API
+
+## Adding demos
diff --git a/pyproject.toml b/pyproject.toml
@@ -30,8 +30,9 @@ docs = [
     "jupytext", # Required to convert .py to .ipynb files
 ]
 
-binder = [
-    "jupyterlab" # Required to interface with Binder when having a Dockerfile in root
+binder = [ # Required to interface with Binder when having a Dockerfile in root
+    "jupyterlab",
+    "notebook"
 ]
 
 [tool.mypy]

Original file line number	Diff line number	Diff line change
`@@ -30,8 +30,9 @@ docs = [`
`30`	`30`	`"jupytext", # Required to convert .py to .ipynb files`
`31`	`31`	`]`
`32`	`32`
`33`		`-binder = [`
`34`		`- "jupyterlab" # Required to interface with Binder when having a Dockerfile in root`
	`33`	`+binder = [ # Required to interface with Binder when having a Dockerfile in root`
	`34`	`+ "jupyterlab",`
	`35`	`+ "notebook"`
`35`	`36`	`]`
`36`	`37`
`37`	`38`	`[tool.mypy]`