Extend the documentation (#96)

Author: btschwertfeger

.github/workflows/_build_doc.yaml

@@ -33,9 +33,10 @@ jobs:
 
       - name: Install dependencies
         run: |
-          python -m pip install --upgrade pip
-          python -m pip install .
-          python -m pip install -r doc/requirements.txt
+          python -m pip install --user --upgrade pip
+          python -m pip install --user .
+          python -m pip install --user -r doc/requirements.txt
+          DEBIAN_FRONTEND=noninteractive sudo apt-get install -y pandoc
 
       - name: Build the documentation
         run: cd doc && make html

Makefile

@@ -25,7 +25,7 @@ build:
 .PHONY: dev
 dev:
 	@git lfs install
-	$(PYTHON) -m pip install -e ".[dev,test]"
+	$(PYTHON) -m pip install -e ".[dev,test,jupyter,examples]"
 
 ## install		Install the package
 ##

README.md

@@ -5,7 +5,7 @@
 [![GitHub](https://badgen.net/badge/icon/github?icon=github&label)](https://github.com/btschwertfeger/python-cmethods)
 [![Generic badge](https://img.shields.io/badge/python-3.8_|_3.9_|_3.10_|_3.11|_3.12-blue.svg)](https://shields.io/)
 [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-orange.svg)](https://www.gnu.org/licenses/gpl-3.0)
-[![Downloads](https://pepy.tech/badge/python-cmethods)](https://pepy.tech/project/python-cmethods)
+[![PyPI Downloads](https://pepy.tech/badge/python-cmethods)](https://pepy.tech/project/python-cmethods)
 
 [![CI/CD](https://github.com/btschwertfeger/python-cmethods/actions/workflows/cicd.yaml/badge.svg?branch=master)](https://github.com/btschwertfeger/python-cmethods/actions/workflows/cicd.yaml)
 [![codecov](https://codecov.io/github/btschwertfeger/python-cmethods/branch/master/graph/badge.svg?token=OSO4PAABPD)](https://codecov.io/github/btschwertfeger/python-cmethods)
@@ -144,6 +144,10 @@ https://python-cmethods.readthedocs.io/en/stable/
 python3 -m pip install python-cmethods
 ```
 
+The package is also available via conda-forge. See
+[conda-forge/python_cmethods-feedstock](https://github.com/conda-forge/python_cmethods-feedstock/tree/main) for more
+information.
+
 <a name="examples"></a>
 
 ## 4. CLI Usage

doc/Makefile

@@ -18,3 +18,4 @@ help:
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+	rm $(SOURCEDIR)/examples.ipynb

doc/conf.py

@@ -27,6 +27,14 @@
 with open("links.rst", encoding="utf-8") as f:
     rst_epilog += f.read()
 
+
+def setup(app) -> None:  # noqa: ARG001
+    from os.path import join
+    from shutil import copyfile
+
+    copyfile(join("..", "examples", "examples.ipynb"), "examples.ipynb")
+
+
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
@@ -38,10 +46,12 @@
     "sphinx.ext.napoleon",
     "sphinx.ext.autosectionlabel",
     "sphinx.ext.mathjax",
+    "nbsphinx",
+    "IPython.sphinxext.ipython_console_highlighting",
 ]
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "links.rst"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "links.rst", "**.ipynb_checkpoints"]
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

doc/getting_started.rst

@@ -18,6 +18,8 @@ The `python-cmethods`_ module can be installed using the package manager pip:
 
     python3 -m pip install python-cmethods
 
+The package is also available via conda-forge. See
+`python_cmethods-feedstock`_ for more information.
 
 Command-Line Interface Usage
 ----------------------------

doc/index.rst

@@ -12,6 +12,7 @@ Welcome to python-cmethods's documentation!
 
    introduction.rst
    getting_started.rst
+   examples.ipynb
    cli.rst
    cmethods.rst
    methods.rst

doc/links.rst

@@ -7,6 +7,8 @@
 
 .. _python-cmethods: https://github.com/btschwertfeger/python-cmethods
 
+.. _python_cmethods-feedstock: https://github.com/conda-forge/python_cmethods-feedstock/tree/main
+
 .. _python-cmethods/issues: https://github.com/btschwertfeger/python-cmethods/issues
 
 .. _python-cmethods/discussions: https://github.com/btschwertfeger/python-cmethods/discussions

doc/requirements.txt

@@ -1,4 +1,6 @@
 cloup
+ipython
+nbsphinx
 netCDF4>=1.6.1
 numpy
 setuptools_scm

examples/examples.ipynb

@@ -4,7 +4,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Example notebook to apply bias adjustment techniques "
+    "# Hands-On Tutorial"
    ]
   },
   {
@@ -28,7 +28,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Define some functions "
+    "## Define some functions "
    ]
   },
   {
@@ -59,7 +59,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Create dummy data"
+    "## Create dummy data"
    ]
   },
   {
@@ -110,7 +110,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Plot created toy data"
+    "## Plot created toy data"
    ]
   },
   {
@@ -151,7 +151,7 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Import module to adjust the data"
+    "## Import module to adjust the data"
    ]
   },
   {
@@ -1211,9 +1211,9 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "🐍 venv repositories/awi-workspace/python-cmethods/venv | Python 3.11.2",
+   "display_name": "python-cmethods",
    "language": "python",
-   "name": "myvenv"
+   "name": "python-cmethods"
   },
   "language_info": {
    "codemirror_mode": {
@@ -1225,7 +1225,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.11.2"
+   "version": "3.10.12"
   },
   "vscode": {
    "interpreter": {

pyproject.toml

@@ -87,6 +87,7 @@ dev = [
   # documentation
   "sphinx",
   "sphinx-rtd-theme",
+  "nbsphinx",
   # linting
   "pylint",
   "flake8",