diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3a93d05..0c4fdc6 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,8 +1,18 @@ # Contributing +## Docstrings + +This project uses [mkdocstrings] to generate API documentation from docstrings. +Write docstrings in the [Numpydoc style]. + +[mkdocstrings]: https://mkdocstrings.github.io/ +[Numpydoc style]: https://mkdocstrings.github.io/griffe/reference/docstrings/#numpydoc-style + ## PR Title Convention -This project uses [Conventional Commits](https://www.conventionalcommits.org/) for **PR titles**. Since we squash-merge, the PR title becomes the final commit message. +This project uses [Conventional Commits] for **PR titles**. Since we squash-merge, the PR title becomes the final commit message. + +[Conventional Commits]: https://www.conventionalcommits.org/ ### Format @@ -12,19 +22,19 @@ type: description ### Allowed Types -| Type | Purpose | -|------|---------| -| `feat` | A new feature | -| `fix` | A bug fix | -| `docs` | Documentation only | -| `style` | Code style (formatting, semicolons, etc.) | +| Type | Purpose | +| ---------- | ------------------------------------------------------- | +| `feat` | A new feature | +| `fix` | A bug fix | +| `docs` | Documentation only | +| `style` | Code style (formatting, semicolons, etc.) | | `refactor` | Code change that neither fixes a bug nor adds a feature | -| `perf` | Performance improvement | -| `test` | Adding or updating tests | -| `build` | Build system or external dependencies | -| `ci` | CI configuration | -| `chore` | Other changes that don't modify src or test files | -| `revert` | Reverts a previous commit | +| `perf` | Performance improvement | +| `test` | Adding or updating tests | +| `build` | Build system or external dependencies | +| `ci` | CI configuration | +| `chore` | Other changes that don't modify src or test files | +| `revert` | Reverts a previous commit | ### Examples diff --git a/docs/api.md b/docs/api.md new file mode 100644 index 0000000..20cca00 --- /dev/null +++ b/docs/api.md @@ -0,0 +1,3 @@ +# API Reference + +::: improved_octo_fortnight.math diff --git a/pyproject.toml b/pyproject.toml index a8c7013..acbd79e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -19,4 +19,4 @@ tag_sign = false check_dirty = false [dependency-groups] -docs = ["zensical"] +docs = ["mkdocstrings-python", "zensical"] diff --git a/src/improved_octo_fortnight/math.py b/src/improved_octo_fortnight/math.py new file mode 100644 index 0000000..abe5af8 --- /dev/null +++ b/src/improved_octo_fortnight/math.py @@ -0,0 +1,64 @@ +"""Basic math operations.""" + + +def add(a, b): + """Add two numbers. + + Parameters + ---------- + a : int or float + The first number. + b : int or float + The second number. + + Returns + ------- + int or float + The sum of `a` and `b`. + + Raises + ------ + TypeError + If `a` or `b` is not a number. + + Examples + -------- + >>> add(1, 2) + 3 + """ + if not isinstance(a, (int, float)) or not isinstance(b, (int, float)): + raise TypeError("Both arguments must be numbers.") + return a + b + + +def fibonacci(n): + """Generate the Fibonacci sequence. + + Parameters + ---------- + n : int + The number of terms to generate. Must be non-negative. + + Returns + ------- + list of int + The first `n` terms of the Fibonacci sequence. + + Raises + ------ + ValueError + If `n` is negative. + + Examples + -------- + >>> fibonacci(6) + [0, 1, 1, 2, 3, 5] + """ + if n < 0: + raise ValueError("n must be non-negative.") + seq = [] + a, b = 0, 1 + for _ in range(n): + seq.append(a) + a, b = b, a + b + return seq diff --git a/zensical.toml b/zensical.toml index 14f236c..a6ffe44 100644 --- a/zensical.toml +++ b/zensical.toml @@ -7,6 +7,7 @@ copyright = "Copyright © 2026 Tai Sakuma" nav = [ { "Get started" = "index.md" }, { "Markdown in 5min" = "markdown.md" }, + { "API Reference" = "api.md" }, ] # extra_css = ["stylesheets/extra.css"] # extra_javascript = ["javascripts/extra.js"] @@ -73,3 +74,17 @@ toggle.name = "Switch to system preference" # [[project.extra.social]] # icon = "fontawesome/brands/github" # link = "https://github.com/user/repo" + +[project.plugins.mkdocstrings.handlers.python] +inventories = ["https://docs.python.org/3/objects.inv"] +paths = ["src"] + +[project.plugins.mkdocstrings.handlers.python.options] +docstring_style = "auto" +inherited_members = true +show_source = false + +[project.plugins.mkdocstrings.handlers.python.options.docstring_options] +method = "heuristics" +style_order = ["numpy", "google", "sphinx"] +default = "numpy"