diff --git a/README.md b/README.md index b2ac15a..fce77d5 100644 --- 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 index c5159a4..ceb3d49 100644 --- 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 index 116df0a..5bc9070 100644 --- 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 new file mode 100644 index 0000000..4695439 --- /dev/null +++ b/docs/part1/coverage.md @@ -0,0 +1 @@ +# Coverage reports diff --git a/docs/part1/linting.md b/docs/part1/linting.md new file mode 100644 index 0000000..63fbab3 --- /dev/null +++ b/docs/part1/linting.md @@ -0,0 +1 @@ +# Python formatting diff --git a/docs/packaging.md b/docs/part1/packaging.md similarity index 69% rename from docs/packaging.md rename to docs/part1/packaging.md index 9abd38d..ea85bb3 100644 --- a/docs/packaging.md +++ b/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) \ No newline at end of file diff --git a/docs/part1/testing.md b/docs/part1/testing.md new file mode 100644 index 0000000..94cfd7d --- /dev/null +++ b/docs/part1/testing.md @@ -0,0 +1 @@ +# Testing \ No newline at end of file diff --git a/docs/part1/typing.md b/docs/part1/typing.md new file mode 100644 index 0000000..445c584 --- /dev/null +++ b/docs/part1/typing.md @@ -0,0 +1 @@ +# Python typing \ No newline at end of file diff --git a/docs/github.md b/docs/part2/citeable.md similarity index 57% rename from docs/github.md rename to docs/part2/citeable.md index 8733b6c..fbc2c5b 100644 --- a/docs/github.md +++ b/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 new file mode 100644 index 0000000..0c9b0d4 --- /dev/null +++ b/docs/part2/github.md @@ -0,0 +1,2 @@ +# Github tools + diff --git a/docs/part2/issues.md b/docs/part2/issues.md new file mode 100644 index 0000000..95ba4c7 --- /dev/null +++ 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 new file mode 100644 index 0000000..562f18b --- /dev/null +++ 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 new file mode 100644 index 0000000..ca7e3d4 --- /dev/null +++ b/docs/part3/auto_api.md @@ -0,0 +1 @@ +# Auto-generation \ No newline at end of file diff --git a/docs/part3/auto_demos.md b/docs/part3/auto_demos.md new file mode 100644 index 0000000..f1fcd58 --- /dev/null +++ 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. \ No newline at end of file diff --git a/docs/part3/publishing.md b/docs/part3/publishing.md new file mode 100644 index 0000000..eb983da --- /dev/null +++ b/docs/part3/publishing.md @@ -0,0 +1,8 @@ +# Building a book + +## File formats + +## `_toc.yml` + +## `_config.yml` + diff --git a/docs/badges.md b/docs/part4/badges.md similarity index 100% rename from docs/badges.md rename to docs/part4/badges.md diff --git a/docs/publishing.md b/docs/publishing.md deleted file mode 100644 index 82dea85..0000000 --- a/docs/publishing.md +++ /dev/null @@ -1,7 +0,0 @@ -# Jupyter-book - -## Building a minimal book - -## Adding Python package API - -## Adding demos \ No newline at end of file