diff --git a/Makefile b/Makefile index 5e9f700..f024e76 100644 --- 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 index ccee369..b2ac15a 100644 --- 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). - - -## Auto-publish to Github Pages - -Add text - -## Jupyter-book - -Add text diff --git a/docs/_toc.yml b/docs/_toc.yml index eb1293b..116df0a 100644 --- 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" \ No newline at end of file diff --git a/docs/badges.md b/docs/badges.md new file mode 100644 index 0000000..3bdb0e0 --- /dev/null +++ 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 new file mode 100644 index 0000000..8733b6c --- /dev/null +++ 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 new file mode 100644 index 0000000..b46a5ff --- /dev/null +++ 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 new file mode 100644 index 0000000..9abd38d --- /dev/null +++ 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) \ No newline at end of file diff --git a/docs/publishing.md b/docs/publishing.md new file mode 100644 index 0000000..82dea85 --- /dev/null +++ b/docs/publishing.md @@ -0,0 +1,7 @@ +# Jupyter-book + +## Building a minimal book + +## Adding Python package API + +## Adding demos \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 8ed8740..1a7ac36 100644 --- 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]