From 95edb5ac8d7b80edef064dd79556e675a191f5a0 Mon Sep 17 00:00:00 2001 From: Weinsen Date: Tue, 3 Dec 2024 23:14:56 -0300 Subject: [PATCH 1/6] Update version --- docs/source/conf.py | 2 +- src/cmdcraft/__init__.py | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 842bbf2..58af305 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -9,7 +9,7 @@ project = "cmdcraft" copyright = "2024, A. M. Weinsen Jr" author = "A. M. Weinsen Jr" -release = "0.0.6" +release = "0.0.7" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/src/cmdcraft/__init__.py b/src/cmdcraft/__init__.py index c183049..9286094 100644 --- a/src/cmdcraft/__init__.py +++ b/src/cmdcraft/__init__.py @@ -6,7 +6,7 @@ from .base import BasePrompter from .prompter import Prompter -__version__ = "0.0.6" +__version__ = "0.0.7" __all__ = [ "BasePrompter", From eeba0475900e7ed588003b7a9619da62528bd800 Mon Sep 17 00:00:00 2001 From: Weinsen Date: Fri, 15 May 2026 09:16:10 -0300 Subject: [PATCH 2/6] chore(infra): add pr template --- .github/pull_request_template.md | 46 ++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 .github/pull_request_template.md diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md new file mode 100644 index 0000000..87b4ea7 --- /dev/null +++ b/.github/pull_request_template.md @@ -0,0 +1,46 @@ +## Summary + +_Describe the change and the user-facing or developer-facing impact._ + +## Related Issues + +Closes #(issue number) or Relates to #(issue number) + +## What Changed + +- _Summarize the code, tests, docs, or tooling changes._ +- _Call out any API, CLI, or behavior changes explicitly._ + +## Type of Change + +- **Bugfix**: Fix an existing feature +- **Feature**: Introduces new functionality without breaking changes +- **Enhancement**: Improves existing functionality +- **Breaking Change**: Introduces breaking changes that require migration +- **Refactoring**: Code restructuring without behavioral changes +- **Build/Infrastructure**: Build system, CI/CD, dependencies, Docker +- **Documentation**: Documentation, comments, or changelog updates + +## Validation + +- `./tools/lint.sh --changed` +- `./tools/test.sh -q` +- `./tools/docs.sh` (if docs or public API changed) +- `python -m build` (if packaging or release files changed) +- Manual testing described below when automated coverage is not enough + +## Breaking Changes + +_Describe any migration, compatibility, or deprecation impact. Write `None` if not applicable._ + +## Notes for Reviewers + +_Call out anything that deserves extra attention: edge cases, tradeoffs, follow-up work, or known limitations._ + +## Checklist + +- Code follows project style guidelines +- Self-review completed +- Comments added for complex logic +- No breaking changes without documentation +- Commit messages follow semantic convention: `{type}({scope}): {message}` From f5da6051777c4053a6da67bdf45318e94f71bc29 Mon Sep 17 00:00:00 2001 From: Weinsen Date: Fri, 15 May 2026 10:04:15 -0300 Subject: [PATCH 3/6] chore(infra): update packaging --- .github/workflows/unit_tests.yml | 19 +++-- pyproject.toml | 111 ++++++++++++++++++++++++++++- requirements.txt | 1 - setup.py | 52 -------------- tools/analyse.sh | 17 ----- tools/common.sh | 118 +++++++++++++++++++++++++++++++ tools/docs.sh | 11 --- tools/format.sh | 15 ++-- tools/lint.sh | 48 +++++++++++++ tools/test.sh | 11 ++- 10 files changed, 307 insertions(+), 96 deletions(-) delete mode 100644 requirements.txt delete mode 100644 setup.py delete mode 100755 tools/analyse.sh create mode 100644 tools/common.sh delete mode 100755 tools/docs.sh create mode 100755 tools/lint.sh diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index 17ba339..f0c2985 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -2,33 +2,40 @@ name: cmdcraft unit testing on: push: - branches: [master] + branches: + - master + - v*-rc pull_request: - branches: [master, v*-rc] + workflow_dispatch: jobs: test: + if: github.event.pull_request.draft == false runs-on: ubuntu-latest strategy: fail-fast: false matrix: - python-version: ["3.10", "3.11", "3.12"] + python-version: ["3.10", "3.11", "3.12", "3.13"] steps: - uses: actions/checkout@v4 + - name: Setup Python ${{ matrix.python-version }} uses: actions/setup-python@v4 with: python-version: ${{ matrix.python-version }} allow-prereleases: true - - name: Install Dependencies + + - name: Install dependencies run: | - sudo apt remove python3-pip python -m pip install --upgrade pip - python -m pip install . ruff coverage pytest readme_renderer + pip install -e '.[dev]' + - name: Analysis run: ./tools/analyse.sh + - name: Tests run: ./tools/test.sh + - name: Validate README.rst run: python -m readme_renderer README.rst \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 7da1ea1..99dddb7 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -1,3 +1,110 @@ +[build-system] +requires = ["setuptools>=69"] +build-backend = "setuptools.build_meta" + +[project] +name = "cmdcraft" +dynamic = ["version"] +description = "Library for building interactive prompt-driven developer tools from Python callables" +readme = { file = "README.rst", content-type = "text/x-rst" } +authors = [{ name = "A. M. Weinsen Jr." }] +license = "BSD-3-Clause" +requires-python = ">=3.10" +dependencies = ["prompt_toolkit>=3.0.52,<4"] +classifiers = [ + "Development Status :: 2 - Pre-Alpha", + "Intended Audience :: Developers", + "Intended Audience :: System Administrators", + "Operating System :: OS Independent", + "Programming Language :: Python", + "Programming Language :: Python :: 3", + "Programming Language :: Python :: 3 :: Only", + "Programming Language :: Python :: 3.10", + "Programming Language :: Python :: 3.11", + "Programming Language :: Python :: 3.12", + "Programming Language :: Python :: 3.13", + "Topic :: Software Development", +] + +[project.optional-dependencies] +dev = [ + "build", + "coverage", + "pytest", + "readme_renderer", + "ruff", +] +docs = [ + "furo", + "sphinx", +] + +[project.urls] +Homepage = "https://github.com/weinsen/cmdcraft" +Repository = "https://github.com/weinsen/cmdcraft" + +[tool.setuptools] +package-dir = {"" = "src"} + +[tool.setuptools.dynamic] +version = {attr = "cmdcraft.__version__"} + +[tool.setuptools.packages.find] +where = ["src"] + +# git-cliff configuration lives in pyproject.toml and is extracted by +# tools/changelog.sh when generating release notes. +[tool.git-cliff.changelog] +header = """ +Changelog +========= + +""" +body = """ +{% if version %}{{ version }} +------------------------------ + +{% else %}Unreleased +------------------------------ + +{% endif %}{% for group, commits in commits | group_by(attribute="group") %}{{ group }} +****************************** + +{% for commit in commits %}- {{ commit.message | trim | upper_first }} +{% endfor %} +{% endfor %} +""" +trim = true +render_always = false + +[tool.git-cliff.git] +conventional_commits = true +filter_unconventional = false +split_commits = false +protect_breaking_commits = false +filter_commits = false +tag_pattern = "v[0-9].*" +topo_order = false +topo_order_commits = true +sort_commits = "oldest" +commit_preprocessors = [ + { pattern = "^new:\\s*", replace = "feat: " }, + { pattern = "^doc:\\s*", replace = "docs: " }, + { pattern = "^infra:\\s*", replace = "chore(infra): " }, +] +commit_parsers = [ + { message = "^feat", group = "Features" }, + { message = "^fix", group = "Bug fixes" }, + { message = "^docs", group = "Documentation" }, + { message = "^test", group = "Testing" }, + { message = "^chore\\(infra\\)", group = "Infrastructure" }, + { message = "^refactor", group = "Refactoring" }, + { message = "^Merge pull request", skip = true }, + { message = "^fixup", skip = true }, + { message = "^Update version$", skip = true }, + { message = "^.*$", group = "Other" }, +] + [tool.ruff] # Exclude a variety of commonly ignored directories. exclude = [ @@ -33,8 +140,8 @@ exclude = [ line-length = 88 indent-width = 4 -# Assume Python 3.8 -target-version = "py38" +# Assume Python 3.10 +target-version = "py310" [tool.ruff.lint] select = ["RUF", "E", "W", "F", "I", "D", "UP"] diff --git a/requirements.txt b/requirements.txt deleted file mode 100644 index 885a9ea..0000000 --- a/requirements.txt +++ /dev/null @@ -1 +0,0 @@ -prompt_toolkit==3.0.47 \ No newline at end of file diff --git a/setup.py b/setup.py deleted file mode 100644 index fb6a0c0..0000000 --- a/setup.py +++ /dev/null @@ -1,52 +0,0 @@ -#!/usr/bin/env python3 -"""Setup cmdcraft library.""" - -import os -import re - -from setuptools import find_packages, setup - -with open(os.path.join(os.path.dirname(__file__), "README.rst")) as f: - """Extract version from README.rst.""" - long_description = f.read() - - -def get_version(package): - """Return package version as listed in `__version__` in `__init__.py`.""" - path = os.path.join(os.path.dirname(__file__), "src", package, "__init__.py") - with open(path, "rb") as f: - init_py = f.read().decode("utf-8") - return re.search("__version__ = ['\"]([^'\"]+)['\"]", init_py).group(1) - - -setup( - name="cmdcraft", - author="A. M. Weinsen Jr.", - version=get_version("cmdcraft"), - url="https://github.com/weinsen/cmdcraft", - description="", - long_description=long_description, - long_description_content_type="text/x-rst", - packages=find_packages(where="src"), - package_dir={"": "src"}, - package_data={"cmdcraft": ["py.typed"]}, - install_requires=["prompt_toolkit"], - python_requires=">=3.10.0", - extras_require={ - "dev": ["ruff", "pytest"], - }, - classifiers=[ - "Development Status :: 2 - Pre-Alpha", - "Intended Audience :: Developers", - "Intended Audience :: System Administrators", - "License :: OSI Approved :: BSD License", - "Operating System :: OS Independent", - "Programming Language :: Python :: 3", - "Programming Language :: Python :: 3.10", - "Programming Language :: Python :: 3.11", - "Programming Language :: Python :: 3.12", - "Programming Language :: Python :: 3 :: Only", - "Programming Language :: Python", - "Topic :: Software Development", - ], -) diff --git a/tools/analyse.sh b/tools/analyse.sh deleted file mode 100755 index 93fd79f..0000000 --- a/tools/analyse.sh +++ /dev/null @@ -1,17 +0,0 @@ -#!/bin/sh -# ***************************************************************************** -# Copyright (c) 2024, Antonio Mario Weinsen Junior -# All rights reserved. -# -# This source code is licensed under the BSD-style license found in the -# LICENSE file in the root directory of this source tree. -# ***************************************************************************** - -# Test only new / modified files -FILES=$(git diff --name-only --diff-filter=d develop | grep -E "(\.py$)") - -if [ -z "${FILES}" ]; then - exit 0 -fi - -ruff check ${FILES} \ No newline at end of file diff --git a/tools/common.sh b/tools/common.sh new file mode 100644 index 0000000..30a8add --- /dev/null +++ b/tools/common.sh @@ -0,0 +1,118 @@ +#!/bin/sh +# ***************************************************************************** +# Copyright (c) 2024-2026, Antonio Mario Weinsen Junior +# All rights reserved. +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. +# ***************************************************************************** + +tool_repo_root() { + git rev-parse --show-toplevel 2>/dev/null || pwd +} + +tool_first_existing_ref() { + for ref in "$@"; do + if [ -n "$ref" ] && git rev-parse --verify --quiet "${ref}^{commit}" >/dev/null; then + printf '%s\n' "$ref" + return 0 + fi + done + + return 1 +} + +tool_python_bin() { + if [ -n "${PYTHON:-}" ]; then + printf '%s\n' "${PYTHON}" + return 0 + fi + + if [ -n "${VIRTUAL_ENV:-}" ] && [ -x "${VIRTUAL_ENV}/bin/python" ]; then + printf '%s\n' "${VIRTUAL_ENV}/bin/python" + return 0 + fi + + repo_root=$(tool_repo_root) + if [ -x "${repo_root}/.venv/bin/python" ]; then + printf '%s\n' "${repo_root}/.venv/bin/python" + return 0 + fi + + if command -v python3 >/dev/null 2>&1; then + printf '%s\n' 'python3' + return 0 + fi + + if command -v python >/dev/null 2>&1; then + printf '%s\n' 'python' + return 0 + fi + + echo 'No Python interpreter found on PATH.' >&2 + return 1 +} + +tool_resolve_base_ref() { + base_ref_override=${TOOLS_BASE_REF:-${CMDCRAFT_BASE_REF:-}} + if [ -n "${base_ref_override}" ]; then + tool_first_existing_ref "${base_ref_override}" "origin/${base_ref_override}" + return $? + fi + + if [ -n "${GITHUB_BASE_REF:-}" ]; then + tool_first_existing_ref "origin/${GITHUB_BASE_REF}" "${GITHUB_BASE_REF}" + return $? + fi + + if [ -n "${GITHUB_SHA:-}" ] && git rev-parse --verify --quiet HEAD^ >/dev/null; then + printf '%s\n' 'HEAD^' + return 0 + fi + + if git symbolic-ref refs/remotes/origin/HEAD >/dev/null 2>&1; then + git symbolic-ref --short refs/remotes/origin/HEAD + return 0 + fi + + tool_first_existing_ref origin/master master origin/main main +} + +tool_tracked_python_files() { + git ls-files '*.py' +} + +tool_changed_python_files() { + all_files=${TOOLS_ALL_FILES:-${CMDCRAFT_ALL_FILES:-0}} + if [ "${all_files}" = "1" ]; then + tool_tracked_python_files + return 0 + fi + + base_ref=$(tool_resolve_base_ref 2>/dev/null || true) + if [ -n "$base_ref" ]; then + git diff --name-only --diff-filter=d "$base_ref" -- '*.py' + return 0 + fi + + tool_tracked_python_files +} + +tool_python_targets() { + tool_changed_python_files | sed '/^$/d' +} + +tool_python_targets_for_scope() { + case "${1:-changed}" in + changed) + tool_changed_python_files + ;; + all) + tool_tracked_python_files + ;; + *) + echo "Unknown scope: ${1}" >&2 + return 1 + ;; + esac | sed '/^$/d' +} \ No newline at end of file diff --git a/tools/docs.sh b/tools/docs.sh deleted file mode 100755 index e3a2282..0000000 --- a/tools/docs.sh +++ /dev/null @@ -1,11 +0,0 @@ -#!/bin/sh -# ***************************************************************************** -# Copyright (c) 2024, Antonio Mario Weinsen Junior -# All rights reserved. -# -# This source code is licensed under the BSD-style license found in the -# LICENSE file in the root directory of this source tree. -# ***************************************************************************** - -rm -rf docs/build -sphinx-build -M html docs/source docs/build \ No newline at end of file diff --git a/tools/format.sh b/tools/format.sh index 22a98c9..027d7e5 100755 --- a/tools/format.sh +++ b/tools/format.sh @@ -1,18 +1,23 @@ #!/bin/sh # ***************************************************************************** -# Copyright (c) 2024, Antonio Mario Weinsen Junior +# Copyright (c) 2024-2026, Antonio Mario Weinsen Junior # All rights reserved. # # This source code is licensed under the BSD-style license found in the # LICENSE file in the root directory of this source tree. # ***************************************************************************** -# Test only new / modified files -FILES=$(git diff --name-only --diff-filter=d develop | grep -E "(\.py$)") +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +. "$SCRIPT_DIR/common.sh" + +PYTHON_BIN=$(tool_python_bin) +FILES=$(tool_python_targets_for_scope changed) if [ -z "${FILES}" ]; then exit 0 fi -ruff check ${FILES} --fix -ruff format ${FILES} \ No newline at end of file +"${PYTHON_BIN}" -m ruff check --fix ${FILES} +"${PYTHON_BIN}" -m ruff format ${FILES} \ No newline at end of file diff --git a/tools/lint.sh b/tools/lint.sh new file mode 100755 index 0000000..409ea04 --- /dev/null +++ b/tools/lint.sh @@ -0,0 +1,48 @@ +#!/bin/bash +# ***************************************************************************** +# Copyright (c) 2024-2026, Antonio Mario Weinsen Junior +# All rights reserved. +# +# This source code is licensed under the BSD-style license found in the +# LICENSE file in the root directory of this source tree. +# ***************************************************************************** + +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +. "$SCRIPT_DIR/common.sh" + +usage() { + echo "Usage: $0 [--all|--changed]" >&2 +} + +scope=all + +case "${1:-}" in + "") + ;; + --all) + scope=all + ;; + --changed) + scope=changed + ;; + -h|--help) + usage + exit 0 + ;; + *) + usage + exit 1 + ;; +esac + +PYTHON_BIN=$(tool_python_bin) +FILES=$(tool_python_targets_for_scope "$scope") + +if [ -z "${FILES}" ]; then + exit 0 +fi + +"${PYTHON_BIN}" -m ruff check ${FILES} +"${PYTHON_BIN}" -m ruff format --check ${FILES} \ No newline at end of file diff --git a/tools/test.sh b/tools/test.sh index ea4480c..88a59f3 100755 --- a/tools/test.sh +++ b/tools/test.sh @@ -1,10 +1,17 @@ #!/bin/sh # ***************************************************************************** -# Copyright (c) 2024, Antonio Mario Weinsen Junior +# Copyright (c) 2024-2026, Antonio Mario Weinsen Junior # All rights reserved. # # This source code is licensed under the BSD-style license found in the # LICENSE file in the root directory of this source tree. # ***************************************************************************** -python3 -m pytest test \ No newline at end of file +set -eu + +SCRIPT_DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd) +. "$SCRIPT_DIR/common.sh" + +PYTHON_BIN=$(tool_python_bin) + +"${PYTHON_BIN}" -m pytest test "$@" \ No newline at end of file From 20459e36ce3f2b3d4eec6342a5572e3abd264fee Mon Sep 17 00:00:00 2001 From: Weinsen Date: Fri, 15 May 2026 17:49:48 -0300 Subject: [PATCH 4/6] chore(infra): update workflow --- .github/workflows/unit_tests.yml | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/.github/workflows/unit_tests.yml b/.github/workflows/unit_tests.yml index f0c2985..be6ea7c 100644 --- a/.github/workflows/unit_tests.yml +++ b/.github/workflows/unit_tests.yml @@ -10,7 +10,7 @@ on: jobs: test: - if: github.event.pull_request.draft == false + if: github.event_name != 'pull_request' || github.event.pull_request.draft == false runs-on: ubuntu-latest strategy: fail-fast: false @@ -19,23 +19,26 @@ jobs: steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 - name: Setup Python ${{ matrix.python-version }} - uses: actions/setup-python@v4 + uses: actions/setup-python@v5 with: python-version: ${{ matrix.python-version }} allow-prereleases: true + cache: pip - name: Install dependencies run: | python -m pip install --upgrade pip pip install -e '.[dev]' - - name: Analysis - run: ./tools/analyse.sh + - name: Lint + run: ./tools/lint.sh --changed - name: Tests run: ./tools/test.sh - name: Validate README.rst - run: python -m readme_renderer README.rst \ No newline at end of file + run: python -m readme_renderer.rst README.rst > /dev/null \ No newline at end of file From a775de255f4cf7aab25cb63d584a5916d3f06e6c Mon Sep 17 00:00:00 2001 From: Weinsen Date: Fri, 15 May 2026 16:52:33 -0300 Subject: [PATCH 5/6] docs: update docs and enable rtd --- .gitignore | 6 ++- .readthedocs.yaml | 19 +++++++++ README.rst | 15 +++++-- docs/Makefile | 27 +++++-------- docs/conf.py | 37 ++++++++++++++++++ docs/{source => }/images/example.gif | Bin docs/index.rst | 24 ++++++++++++ docs/make.bat | 35 ----------------- CHANGELOG.rst => docs/pages/changelog.rst | 4 +- .../pages/contributing.rst | 8 +++- docs/pages/documentation.rst | 20 ++++++++++ docs/{source => }/pages/howto/crafting.rst | 0 .../pages/intro/getting_started.rst | 0 docs/{source => }/pages/intro/index.rst | 0 .../{source => }/pages/intro/known_issues.rst | 0 docs/source/conf.py | 27 ------------- docs/source/index.rst | 32 --------------- docs/source/pages/documentation.rst | 14 ------- pyproject.toml | 12 ++++-- 19 files changed, 143 insertions(+), 137 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/conf.py rename docs/{source => }/images/example.gif (100%) create mode 100644 docs/index.rst delete mode 100644 docs/make.bat rename CHANGELOG.rst => docs/pages/changelog.rst (96%) rename CONTRIBUING.rst => docs/pages/contributing.rst (80%) create mode 100644 docs/pages/documentation.rst rename docs/{source => }/pages/howto/crafting.rst (100%) rename docs/{source => }/pages/intro/getting_started.rst (100%) rename docs/{source => }/pages/intro/index.rst (100%) rename docs/{source => }/pages/intro/known_issues.rst (100%) delete mode 100644 docs/source/conf.py delete mode 100644 docs/source/index.rst delete mode 100644 docs/source/pages/documentation.rst diff --git a/.gitignore b/.gitignore index 3c5b2a1..e2b54de 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,12 @@ # Python +.venv/ *__pycache__* **/.pyc tmp/ -docs/build/ *.egg *.egg-info dist -build +build/ +_build/ +docs/html/ eggs \ No newline at end of file diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..4f7d909 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,19 @@ +version: 2 +build: + os: ubuntu-24.04 + tools: + python: "3.12" + +sphinx: + configuration: docs/conf.py + +python: + install: + - method: pip + path: . + extra_requirements: + - docs + +formats: + - epub + - pdf \ No newline at end of file diff --git a/README.rst b/README.rst index f8499de..6fcd8cd 100644 --- a/README.rst +++ b/README.rst @@ -1,11 +1,14 @@ cmdcraft ======== +.. image:: https://github.com/weinsen/cmdcraft/actions/workflows/unit_tests.yml/badge.svg?branch=master + :target: https://github.com/weinsen/cmdcraft/actions/workflows/unit_tests.yml + ``cmdcraft`` is a library that aims to build fast and stable -interative devtools. It that native Python metadata from objects to build prompt +interactive devtools. It uses native Python metadata from objects to build prompt commands, so you don't have to manually configure input options. -.. image:: docs/source/images/example.gif +.. image:: docs/images/example.gif Features -------- @@ -18,7 +21,13 @@ Features Contributing ============ -Contributions are welcome! Please start by reading the `Contributing Guidelines `_ file. +Contributions are welcome! Please start by reading the `Contributing Guidelines `_ file. + +License +======= + +This project is licensed under the BSD-style license found in the LICENSE file in the +root directory of this source tree. Special thanks ============== diff --git a/docs/Makefile b/docs/Makefile index d0c3cbf..1ff5007 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,20 +1,13 @@ -# Minimal makefile for Sphinx documentation -# +PYTHON ?= python +SPHINXBUILD = $(PYTHON) -m sphinx +SPHINXAPIDOC = $(PYTHON) -m sphinx.ext.apidoc +SOURCEDIR = . +BUILDDIR = _build -# You can set these variables from the command line, and also -# from the environment for the first two. -SPHINXOPTS ?= -SPHINXBUILD ?= sphinx-build -SOURCEDIR = source -BUILDDIR = build +.PHONY: apidoc html -# Put it first so that "make" without argument is like "make help". -help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +apidoc: + $(SPHINXAPIDOC) -f -e -o _generated ../src/cmdcraft -.PHONY: help Makefile - -# Catch-all target: route all unknown targets to Sphinx using the new -# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). -%: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) +html: + $(SPHINXBUILD) -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..0248f7b --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,37 @@ +"""Sphinx configuration for the cmdcraft documentation.""" + +project = "cmdcraft" +copyright = "2026, A. M. Weinsen Jr" +author = "A. M. Weinsen Jr" +release = "0.0.7" + +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.autosummary", + "sphinx.ext.napoleon", + "sphinx.ext.viewcode", + "sphinx_autodoc_typehints", +] + +autodoc_default_options = { + "members": True, + "undoc-members": False, + "private-members": False, + "show-inheritance": True, + "inherited-members": True, +} + +autodoc_typehints = "description" +napoleon_google_docstring = True +autosummary_generate = True +autosummary_imported_members = False + +templates_path = ["_templates"] +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +html_theme = "sphinx_rtd_theme" +html_static_path = ["_static"] +html_title = f"{project} {release} documentation" + +# Explicit root doc (Sphinx defaults to 'index' but be explicit). +root_doc = "index" diff --git a/docs/source/images/example.gif b/docs/images/example.gif similarity index 100% rename from docs/source/images/example.gif rename to docs/images/example.gif diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..24fe20b --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,24 @@ +Welcome to cmdcraft documentation! +================================== + +``cmdcraft`` is a library that aims to build fast and stable +interactive devtools. It uses native Python metadata from objects to build prompt +commands, so you don't have to manually configure input options. + +Table of Contents +----------------- + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + pages/intro/index + pages/howto/crafting + pages/contributing + pages/changelog + pages/documentation + +Special thanks +============== + +- `Python Prompt Toolkit `_: Awesome prompt utility. \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 747ffb7..0000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.https://www.sphinx-doc.org/ - exit /b 1 -) - -if "%1" == "" goto help - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/CHANGELOG.rst b/docs/pages/changelog.rst similarity index 96% rename from CHANGELOG.rst rename to docs/pages/changelog.rst index a5b7fe6..c46f76d 100644 --- a/CHANGELOG.rst +++ b/docs/pages/changelog.rst @@ -28,7 +28,7 @@ v0.0.4 - Improve linting Fixed issues: -****** +************* #2: Exception while typing quoted arguments v0.0.3 @@ -40,7 +40,7 @@ v0.0.3 v0.0.2 Fixed issues: -****** +************* #1: Input mishandling options - Input handling diff --git a/CONTRIBUING.rst b/docs/pages/contributing.rst similarity index 80% rename from CONTRIBUING.rst rename to docs/pages/contributing.rst index 79da79f..b8e1cb8 100644 --- a/CONTRIBUING.rst +++ b/docs/pages/contributing.rst @@ -28,4 +28,10 @@ we ask to start the brief message with one of these tags: - `infra`: The commit contains changes to the project infrastructure Also, if the commit is related to a specific tracked issue, please insert its number -preceded by #. \ No newline at end of file +preceded by #. + +Local checks +============ + +Use ``./tools/lint.sh --changed`` to lint only the Python files changed on your branch, +or ``./tools/lint.sh --all`` for a full-repository Ruff check plus formatting validation. diff --git a/docs/pages/documentation.rst b/docs/pages/documentation.rst new file mode 100644 index 0000000..c1c309d --- /dev/null +++ b/docs/pages/documentation.rst @@ -0,0 +1,20 @@ +Documentation +============= + +BasePrompter +------------ + +.. automodule:: cmdcraft.base + :members: + +Prompter +-------- + +.. automodule:: cmdcraft.prompter + :members: + +Command +------- + +.. automodule:: cmdcraft.command + :members: \ No newline at end of file diff --git a/docs/source/pages/howto/crafting.rst b/docs/pages/howto/crafting.rst similarity index 100% rename from docs/source/pages/howto/crafting.rst rename to docs/pages/howto/crafting.rst diff --git a/docs/source/pages/intro/getting_started.rst b/docs/pages/intro/getting_started.rst similarity index 100% rename from docs/source/pages/intro/getting_started.rst rename to docs/pages/intro/getting_started.rst diff --git a/docs/source/pages/intro/index.rst b/docs/pages/intro/index.rst similarity index 100% rename from docs/source/pages/intro/index.rst rename to docs/pages/intro/index.rst diff --git a/docs/source/pages/intro/known_issues.rst b/docs/pages/intro/known_issues.rst similarity index 100% rename from docs/source/pages/intro/known_issues.rst rename to docs/pages/intro/known_issues.rst diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 58af305..0000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,27 +0,0 @@ -# Configuration file for the Sphinx documentation builder. -# -# For the full list of built-in configuration values, see the documentation: -# https://www.sphinx-doc.org/en/master/usage/configuration.html - -# -- Project information ----------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information - -project = "cmdcraft" -copyright = "2024, A. M. Weinsen Jr" -author = "A. M. Weinsen Jr" -release = "0.0.7" - -# -- General configuration --------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration - -extensions = ["sphinx.ext.autodoc"] - -templates_path = ["_templates"] -exclude_patterns = [] - - -# -- Options for HTML output ------------------------------------------------- -# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output - -html_theme = "furo" -html_static_path = ["_static"] diff --git a/docs/source/index.rst b/docs/source/index.rst deleted file mode 100644 index 27909f4..0000000 --- a/docs/source/index.rst +++ /dev/null @@ -1,32 +0,0 @@ -cmdcraft documentation -========================== - -cmdcraft (or simply ``cmdcraft``) is a library that aims to build fast and stable -interative devtools. It that native Python metadata from objects to build prompt -commands, so you don't have to manually configure input options. - -.. image:: images/example.gif - -Features --------- - -- Asynchronous and parallel tasks using asyncio -- Easy function to command interface -- Out of box functionality -- Intuitive usability - -Table of Contents ------------------ - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - pages/intro/index - pages/howto/crafting - pages/documentation - -Special thanks -============== - -- `Python Prompt Toolkit `_: Awesome prompt utility. \ No newline at end of file diff --git a/docs/source/pages/documentation.rst b/docs/source/pages/documentation.rst deleted file mode 100644 index fbc6b72..0000000 --- a/docs/source/pages/documentation.rst +++ /dev/null @@ -1,14 +0,0 @@ -Documentation -============= - -Prompter ------------ - -.. automodule:: cmdcraft.interpreter - :members: - -Command ------------ - -.. automodule:: cmdcraft.command - :members: \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index 99dddb7..abd371b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -35,13 +35,17 @@ dev = [ "ruff", ] docs = [ - "furo", - "sphinx", + "sphinx>=6.0", + "sphinx-rtd-theme", + "sphinx-autodoc-typehints", + "sphinx-autobuild", ] [project.urls] -Homepage = "https://github.com/weinsen/cmdcraft" -Repository = "https://github.com/weinsen/cmdcraft" +"Homepage" = "https://github.com/weinsen/cmdcraft" +"Repository" = "https://github.com/weinsen/cmdcraft" +"Bug Reports" = "https://github.com/weinsen/cmdcraft/issues" +"Docs" = "https://cmdcraft.readthedocs.io/en/latest/?badge=latest" [tool.setuptools] package-dir = {"" = "src"} From 25b6a95ad0e8d067cb48e8ef7b5e0032d5788783 Mon Sep 17 00:00:00 2001 From: Weinsen Date: Fri, 15 May 2026 21:08:23 -0300 Subject: [PATCH 6/6] Update changelog --- docs/pages/changelog.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/pages/changelog.rst b/docs/pages/changelog.rst index c46f76d..bc9dce8 100644 --- a/docs/pages/changelog.rst +++ b/docs/pages/changelog.rst @@ -1,6 +1,14 @@ Changelog ========= +v0.0.7 +---------- + +- Move packaging metadata into ``pyproject.toml`` and remove ``setup.py`` plus ``requirements.txt``. +- Add shared tooling helpers and dedicated ``lint`` / ``test`` scripts that honor the repository virtual environment and base ref. +- Expand GitHub Actions coverage to Python 3.13, release-candidate branches, editable installs, and draft PR handling. +- Reorganize the Sphinx docs for Read the Docs, add API documentation pages, and document the updated contributor workflow. + v0.0.6 ------