Rename (#7)

* ♻️ use only two names, reduce template complexity a bit

* 🎨 describe and format cicd GitHub Action

* 🎨 remove headings ( toc tree is not included in overview)

* 🎨 update tutorial with some more comments

* 🎨 add cross-reference to api doc and print docstring

* 🎨 change link text

* 💥 require minimal supported Python version, fix parameter in docstring

Author: enryH

.github/workflows/README.md

@@ -0,0 +1,11 @@
+# Workflows
+
+## cicd
+
+Basic continuous integration and deployment (CI/CD) workflow for Python packages.
+
+- checks formatting (black)
+- checks linting (ruff)
+- run unit tests (pytest)
+- optional: add c extensions to a package
+- if all checks pass, build and deploy to PyPI if `tag` triggered the workflow

.github/workflows/cicd.yml

@@ -6,20 +6,19 @@ name: Python application
 on:
   push:
   pull_request:
-    branches: [ "main" ]
+    branches: ["main"]
   schedule:
-    - cron: '0 2 * * 3'
+    - cron: "0 2 * * 3"
 
 permissions:
   contents: read
 
-
 jobs:
   format:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-      - uses: psf/black@stable 
+      - uses: psf/black@stable
   lint:
     name: Lint with ruff
     runs-on: ubuntu-latest
@@ -30,9 +29,9 @@ jobs:
         with:
           python-version: "3.11"
       - name: Install ruff
-        run: | 
+        run: |
           pip install ruff
-      - name: Lint with ruff  
+      - name: Lint with ruff
         run: |
           # stop the build if there are Python syntax errors or undefined names
           ruff check .
@@ -48,36 +47,36 @@ jobs:
         uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
-          cache: 'pip' # caching pip dependencies
-          cache-dependency-path: '**/pyproject.toml'
+          cache: "pip" # caching pip dependencies
+          cache-dependency-path: "**/pyproject.toml"
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
           pip install pytest
           pip install -e .
       - name: Run tests
         run: python -m pytest tests
-  
+
   build_source_dist:
     name: Build source distribution
     if: startsWith(github.ref, 'refs/heads/main') || startsWith(github.ref, 'refs/tags')
     runs-on: ubuntu-latest
     steps:
-        - uses: actions/checkout@v4
+      - uses: actions/checkout@v4
 
-        - uses: actions/setup-python@v5
-          with:
-            python-version: "3.10"
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
 
-        - name: Install build
-          run: python -m pip install build
+      - name: Install build
+        run: python -m pip install build
 
-        - name: Run build
-          run: python -m build --sdist
+      - name: Run build
+        run: python -m build --sdist
 
-        - uses: actions/upload-artifact@v4
-          with:
-            path: ./dist/*.tar.gz
+      - uses: actions/upload-artifact@v4
+        with:
+          path: ./dist/*.tar.gz
   # Needed in case of building packages with external binaries (e.g. Cython, RUst-extensions, etc.)
   # build_wheels:
   #   name: Build wheels on ${{ matrix.os }}
@@ -105,25 +104,25 @@ jobs:
   #           path: ./wheels/*.whl
 
   publish:
-      name: Publish package
-      if: startsWith(github.ref, 'refs/tags')
-      needs:
-          - format
-          - lint
-          - test
-          - build_source_dist
-          # - build_wheels
-      runs-on: ubuntu-latest
-
-      steps:
-          - uses: actions/download-artifact@v4
-            with:
-              name: artifact
-              path: ./dist
-
-          - uses: pypa/gh-action-pypi-publish@release/v1
-            with:
-              # remove repository key to set the default to pypi (not test.pypi.org) 
-              repository-url: https://test.pypi.org/legacy/
-              user: __token__
-              password: ${{ secrets.PYPI_API_TOKEN }}
+    name: Publish package
+    if: startsWith(github.ref, 'refs/tags')
+    needs:
+      - format
+      - lint
+      - test
+      - build_source_dist
+      # - build_wheels
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: artifact
+          path: ./dist
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # remove repository key to set the default to pypi (not test.pypi.org)
+          repository-url: https://test.pypi.org/legacy/
+          user: __token__
+          password: ${{ secrets.PYPI_API_TOKEN }}

README.md

@@ -5,126 +5,12 @@
 Can be used as GitHub template repository,
 see [GitHub documentation](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template).
 
-You will need to find and replace occurences of 
+You will need to find and replace occurences of
 
-- `mockup` -> `your_package_name`
-- `rasmussenlab-mockup` -> `your_package_name`
-- `RasmussenLab` -> `GitHub_user_name` (or organization)
 - `python_package` -> `your_package_name`
+- `RasmussenLab` -> `GitHub_user_name` (or `organization`)
 
-with the name of your package and GitHub user name (or organization). This still might
-need further testing:
-
-```bash
-# currently these are (v24.03)
-
-pyproject.toml:
-  5  description = "A small example package"
-  6: name = "rasmussenlab-mockup"
-  7  # This means: Load the version from the package itself.
-
-README.md:
-   7  
-   8: You will need to find and replace occurences of `mockup` with the name of your package. This still might
-   9  need further testing.
-
-  22  
-  23: Install vom [TestPyPI](https://test.pypi.org/project/rasmussenlab-mockup):
-  24  
-  25  ```
-  26: pip install -i https://test.pypi.org/simple/ rasmussenlab-mockup
-  27  ```
-  28  
-  29: > The package on PyPI is call `rasmussenlab-mockup` and not `mockup` as the package name is already taken. The import is still `import mockup`.
-  30  
-
-docs\conf.py:
-   18  
-   19: project = "mockup"
-   20  copyright = "2024, Jakob Nybo Nissen, Henry Webel"
-   21  author = "Jakob Nybo Nissen, Henry Webel"
-   22: PACKAGE_VERSION = metadata.version("rasmussenlab-mockup")
-   23  version = PACKAGE_VERSION
-
-  119      PROJECT_ROOT = Path(__file__).parent.parent
-  120:     PACKAGE_ROOT = PROJECT_ROOT / "src" / "mockup"
-  121  
-
-docs\index.rst:
-   1: .. mockup documentation master file, created by
-   2     sphinx-quickstart on Mon Aug 28 14:09:15 2023.
-
-   5  
-   6: The mockup package
-   7  ==================================
-   8  
-   9: Mockup is a Python package with some simple example code.
-  10: To get started, explore the :class:`mockup.Circle` class.
-  11  
-
-docs\README.md:
-  27  # apidoc
-  28: sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/mockup
-  29  # build docs
-
-docs\tutorial\tutorial.ipynb:
-   6     "source": [
-   7:     "# Mockup tutorial"
-   8     ]
-
-  15     "source": [
-  16:     "from mockup import mockup"
-  17     ]
-
-  24     "source": [
-  25:     "mockup.add_one(-11)"
-  26     ]
-
-  33     "source": [
-  34:     "list(mockup.flatten_ints([[9, 11], [12], [4, 5]]))"
-  35     ]
-
-  42     "source": [
-  43:     "c2 = mockup.Circle.from_circumference(100)\n",
-  44      "round(c2.radius, 3)"
-
-src\mockup\__init__.py:
-  6  
-  7: __version__ = metadata.version("rasmussenlab-mockup")
-  8  
-  9: from .mockup import add_one, Circle
-  10  
-
-tests\test_circle.py:
-  1  import unittest
-  2: from mockup.mockup import Circle
-  3  
-```
-
-And additionally the author names:
-
-```bash
-pyproject.toml:
-  1  [project]
-  2: authors = [
-  3    {name = "Jakob Nybo Nissen", email = "[email protected]"},
-
-README.md:
-  37     20  copyright = "2024, Jakob Nybo Nissen, Henry Webel"
-  38:    21  author = "Jakob Nybo Nissen, Henry Webel"
-  39     22: PACKAGE_VERSION = metadata.version("rasmussenlab-mockup")
-
-  96  
-  97: And additionally the author names:
-  98  
-
-docs\conf.py:
-  20  copyright = "2024, Jakob Nybo Nissen, Henry Webel"
-  21: author = "Jakob Nybo Nissen, Henry Webel"
-  22  PACKAGE_VERSION = metadata.version("rasmussenlab-mockup")
-```
-
-> Potentially a cookiecutter could be based on this template repository.
+with the name of your package and GitHub user name (or organization).
 
 ## Development environment
 
@@ -134,20 +20,19 @@ Install package so that new code is picked up in a restared python interpreter:
 pip install -e ".[dev]"
 ```
 
-## TestPyPI
+## Basic usage
 
-Install vom [TestPyPI](https://test.pypi.org/project/rasmussenlab-mockup):
-
-```
-pip install -i https://test.pypi.org/simple/ rasmussenlab-mockup
+```python
+from python_package import hello_world
+print (python_package.__version__)
+print(hello_world(4))
 ```
 
-> The package on PyPI is call `rasmussenlab-mockup` and not `mockup` as the package name is already taken. The import is still `import mockup`.
-
 ## Readthedocs
 
-The documentation is build using readthedocs automatically. See 
-[project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/).
+The documentation can be build using readthedocs automatically. See
+[project on Readthedocs](https://readthedocs.org/projects/rasmussenlab-python-package/) for the project. A new project needs
+to be registered.
 
 - make sure to enable build from PRs in the settings (advanded settings)
 - checkout configuration file: [`.readthedocs.yaml`](.readthedocs.yaml)

docs/README.md

@@ -25,7 +25,7 @@ Options:
 ```bash	
 # pwd: docs
 # apidoc
-sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/mockup
+sphinx-apidoc --force --implicit-namespaces --module-first -o reference ../src/python_package
 # build docs
 sphinx-build -n -W --keep-going -b html ./ ./_build/
 ```

docs/conf.py

@@ -15,10 +15,10 @@
 
 # -- Project information -----------------------------------------------------
 
-project = "mockup"
-copyright = "2024, Jakob Nybo Nissen, Henry Webel"
+project = "python_package"
+copyright = "2025, Jakob Nybo Nissen, Henry Webel"
 author = "Jakob Nybo Nissen, Henry Webel"
-PACKAGE_VERSION = metadata.version("rasmussenlab-mockup")
+PACKAGE_VERSION = metadata.version("python_package")
 version = PACKAGE_VERSION
 release = PACKAGE_VERSION
 
@@ -128,7 +128,7 @@
     from pathlib import Path
 
     PROJECT_ROOT = Path(__file__).parent.parent
-    PACKAGE_ROOT = PROJECT_ROOT / "src" / "mockup"
+    PACKAGE_ROOT = PROJECT_ROOT / "src" / "python_package"
 
     def run_apidoc(_):
         from sphinx.ext import apidoc

docs/index.md

@@ -0,0 +1,39 @@
+# Python Package Documentation
+
+```{include} ../README.md
+:start-line: 0
+:relative-docs: docs
+:relative-images:
+```
+
+<!-- hidden toc trees for sidebar -->
+
+```{toctree}
+:maxdepth: 2
+:caption: "Tutorials"
+:hidden: true
+
+tutorial/tutorial
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: "Reference"
+:hidden: true
+
+reference/python_package
+```
+
+```{toctree}
+:maxdepth: 2
+:caption: "Technical notes"
+:hidden: true
+
+README
+```
+
+## Indices and tables
+
+- [Index](genindex)
+- [Module Index](modindex)
+- [Search](search)