Tutorial - draft

docs/tutorial/code_quality/code_quality.md

@@ -0,0 +1,11 @@
+# Code quality
+
+intro
+
+???question "Why standardizing my code?"
+    Allows running tools
+
+- [pre-commit hooks](pre_commit_hooks.md)
+- [formatter: black](formatter.md)
+- [type_checking: mypy](type_checking.md)
+- [linter: ruff](linter.md)

docs/tutorial/code_quality/formatter.md

@@ -0,0 +1,14 @@
+# Formatting code with black
+
+Why manually bother to format your code when you can automate it?
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+    ...
+
+  - repo: https://github.com/psf/black
+    rev: 23.1.0
+    hooks:
+      - id: black
+
+```

docs/tutorial/code_quality/linter.md

@@ -0,0 +1,53 @@
+# Linting with ruff
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+  ...
+
+  - repo: https://github.com/charliermarsh/ruff-pre-commit
+    rev: v0.0.257
+    hooks:
+      - id: ruff
+        args: [--fix]
+
+```
+
+```toml title="pyproject.toml"
+# https://github.com/charliermarsh/ruff
+[tool.ruff]
+line-length = 88
+target-version = "py38"
+# https://beta.ruff.rs/docs/rules/
+extend-select = [
+    "E",    # style errors
+    "W",    # style warnings
+    "F",    # flakes
+    "D",    # pydocstyle
+    "I",    # isort
+    "U",    # pyupgrade
+    # "S",    # bandit
+    "C",    # flake8-comprehensions
+    "B",    # flake8-bugbear
+    "A001", # flake8-builtins
+    "RUF",  # ruff-specific rules
+]
+# I do this to get numpy-style docstrings AND retain
+# D417 (Missing argument descriptions in the docstring)
+# otherwise, see:
+# https://beta.ruff.rs/docs/faq/#does-ruff-support-numpy-or-google-style-docstrings
+# https://github.com/charliermarsh/ruff/issues/2606
+extend-ignore = [
+    "D100", # Missing docstring in public module
+    "D107", # Missing docstring in __init__
+    "D203", # 1 blank line required before class docstring
+    "D212", # Multi-line docstring summary should start at the first line
+    "D213", # Multi-line docstring summary should start at the second line
+    "D401", # First line should be in imperative mood
+    "D413", # Missing blank line after last section
+    "D416", # Section name should end with a colon
+]
+
+[tool.ruff.per-file-ignores]
+"tests/*.py" = ["D", "S"]
+"setup.py" = ["D"]
+```

docs/tutorial/code_quality/pre_commit_hooks.md

@@ -0,0 +1,18 @@
+# pre-commit
+
+Clean your room before going out!
+
+```text title="File Structure"
+src/
+└── pydev_tutorial/
+    ├── __init__.py
+.pre-commit-config.yaml
+```
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+  - repo: https://github.com/abravalheri/validate-pyproject
+    rev: v0.12.1
+    hooks:
+      - id: validate-pyproject
+```

docs/tutorial/code_quality/type_checking.md

@@ -0,0 +1,26 @@
+# Enforce types with mypy
+
+```yaml title=".pre-commit-config.yaml"
+repos:
+  ...
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.1.1
+    hooks:
+      - id: mypy
+        files: "^src/"
+        # # you have to add the things you want to type check against here
+        # additional_dependencies:
+        #   - numpy
+```
+
+```toml title="pyproject.toml"
+# https://mypy.readthedocs.io/en/stable/config_file.html
+[tool.mypy]
+files = "src/**/"
+strict = true
+disallow_any_generics = false
+disallow_subclassing_any = false
+show_error_codes = true
+pretty = true
+```

docs/tutorial/github/continuous_integration.md

@@ -0,0 +1,90 @@
+# Continuous integration with Actions
+
+```text title="File Structure"
+.github/
+└── workflows/
+    └── ci.yaml
+src/
+tests/
+```
+
+```yaml title="ci.yaml"
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # run every week (for --pre release tests)
+    - cron: "0 0 * * 0"
+
+jobs:
+  check-manifest:
+    # check-manifest is a tool that checks that all files in version control are
+    # included in the sdist (unless explicitly excluded)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: pipx run check-manifest
+
+  test:
+    name: ${{ matrix.platform }} (${{ matrix.python-version }})
+    runs-on: ${{ matrix.platform }}
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.8", "3.9", "3.10", "3.11"]
+        platform: [ubuntu-latest, macos-latest, windows-latest]
+
+    steps:
+      - name: 🛑 Cancel Previous Runs
+        uses: styfle/cancel-workflow-action@0.11.0
+        with:
+          access_token: ${{ github.token }}
+
+      - uses: actions/checkout@v3
+
+      - name: 🐍 Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v4
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache-dependency-path: "pyproject.toml"
+          cache: "pip"
+
+      - name: Install pip
+        run: |
+          python -m pip install -U pip
+
+      # if running a cron job, we add the --pre flag to
+      # test against pre-releases
+      - name: Install Dependencies
+        run: >
+          python -m pip install .[test]
+          ${{ github.event_name == 'schedule' && '--pre' || ''  }}
+
+      - name: 🧪 Run Tests
+        run: pytest --color=yes --cov --cov-report=xml --cov-report=term-missing
+
+      # If something goes wrong with --pre tests,
+      # we can open an issue in the repo
+      - name: 📝 Report --pre Failures
+        if: failure() && github.event_name == 'schedule'
+        uses: JasonEtco/create-an-issue@v2
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          PLATFORM: ${{ matrix.platform }}
+          PYTHON: ${{ matrix.python-version }}
+          RUN_ID: ${{ github.run_id }}
+          TITLE: "[test-bot] pip install --pre is failing"
+        with:
+          filename: .github/TEST_FAIL_TEMPLATE.md
+          update_existing: true
+
+      - name: Coverage
+        uses: codecov/codecov-action@v3
+```

docs/tutorial/github/deployment.md

@@ -0,0 +1,55 @@
+# Deployment to PyPi
+
+## Secrets
+
+```yaml
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*"
+  pull_request:
+  workflow_dispatch:
+  schedule:
+    # run every week (for --pre release tests)
+    - cron: "0 0 * * 0"
+
+jobs:
+  ...
+
+  deploy:
+    name: Deploy
+    needs: test
+    if: >
+      success()
+      && startsWith(github.ref, 'refs/tags/')
+      && github.event_name != 'schedule'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: 🐍 Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.x"
+
+      - name: 👷 Build
+        run: |
+          python -m pip install build
+          python -m build
+
+      - name: 🚢 Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.TWINE_API_KEY }}
+
+      - uses: softprops/action-gh-release@v1
+        with:
+          generate_release_notes: true
+
+```

docs/tutorial/github/github_apps.md

@@ -0,0 +1,5 @@
+# Using Github apps
+
+## Codecov
+
+## Pre-commit

docs/tutorial/pre_requisite/ide.md

@@ -0,0 +1,13 @@
+# IDE: VSCode
+
+## Download and install VSCode
+
+## Basics
+
+## Debugging
+
+## Some settings
+
+### Starting from the command line
+
+### Setting a ruler

docs/tutorial/pre_requisite/version_control.md

@@ -0,0 +1,25 @@
+# Git
+
+Link to tutorial
+
+=== "macOS"
+
+    1.
+
+=== "Linux"
+
+    1.
+
+=== "Windows"
+
+    1. Git for Windows
+
+## Typical workflow
+
+```shell
+git status
+git checkout -b mybranch
+git add
+git commit -m ""
+git push
+```

docs/tutorial/pre_requisite/virtual_environment.md

@@ -0,0 +1,5 @@
+# Virtual environments with Conda
+
+miniconda
+
+mamba?

docs/tutorial/summary.md

@@ -0,0 +1,43 @@
+
+# Summary
+
+Tooling, testing, packaging... These are words floating around but they sound
+like work and we all have enough of that already, so why bother? In the end, you
+just want code that works and that can be used by people!
+
+And that's exactly where tooling comes in. In this tutorial, we are going to
+walk you through a set of tools. Each section is straightforward and shouldn't
+take long to absorb. This is the pyramid scheme of programming: **for a small
+investment you will get high returns**.
+
+!!!tip "What are these tools for?"
+    These tools are all about automating the tedious tasks and forcing you to
+    perform the  dull chores bit by bit rather than just before release!
+
+Here is a list of the main tools we will go over:
+
+- `Conda`: virtual environments to code in a safe space.
+- `git`: keep track of changes and benefit from all the advantages of Github.
+- `VSCode`: a lightweight IDE to be more effective at writing and debugging
+code.
+- `pyproject.toml`: a single file with all your Python packaging information.
+- `pytest`: get in the habit of writing tests to make your code bullet-proof.
+- `black`: make your code more readable using automatic formatting.
+- `mypy`: enforce types, and never be surprised by inputs and outputs.
+- `ruff`: improve code quality using a linter.
+- `codecov`: find the blind spots of your tests.
+- `pre-commit`: automate formatter, linter, or type checker before every commit.
+- `Github actions`: automate everything everywhere all at once!
+
+Apply these tools and you will see the result rapidly![^1]
+
+!!! note "Example repositories"
+    This tutorial guides you through the same tools that are automatically
+    installed if you create a repository using
+    [pyrepo-copier](https://github.com/pydev-guide/pyrepo-copier).
+
+    Finally, in this tutorial we also create some code. The
+    [pydev-tutorial](https://github.com/pydev-guide/pydev-tutorial) repository
+    corresponds to what you will implement by following this step by step.
+
+[^1]: Did you know that 9 out of 10 programmers recommend these tools?