From ca1966d7dfbc6ea57663712eabef9467f5665c68 Mon Sep 17 00:00:00 2001 From: Jayaram Kancherla Date: Tue, 10 Dec 2024 15:08:02 -0800 Subject: [PATCH] Minor changes to improve UX (#3) Update tests, docstring, README etc. --- CHANGELOG.md | 6 ++++- README.md | 5 ++++ docs/conf.py | 21 +++++++++++++-- docs/requirements.txt | 1 + src/biocsetup/cli.py | 4 +-- src/biocsetup/create_repository.py | 42 ++++++++++++++++++++++-------- tests/test_cli.py | 2 +- 7 files changed, 64 insertions(+), 17 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index ebf2170..2ff6d6f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Changelog +## Version 0.1.1 + +Minor changes to improve user experience. + ## Version 0.1.0 - Uses PyScaffold with Markdown extension for base project structure @@ -10,4 +14,4 @@ - Furo theme - Type hints documentation - Adds Ruff configuration for consistent code formatting -- Creates standardized README with PyPI and CI badges +- Creates README diff --git a/README.md b/README.md index d315e53..657fcd1 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,11 @@ create_repository( ) ``` +## After setup + +- (Optional) Enable [pre-commit.ci](https://pre-commit.ci/) bot for your new repository. +- (Optional) Install [ruff](https://docs.astral.sh/ruff/) for code formatting. + ## Note diff --git a/docs/conf.py b/docs/conf.py index f423b6b..eb41901 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -171,7 +171,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = "alabaster" +html_theme = "furo" # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -301,4 +301,21 @@ "pyscaffold": ("https://pyscaffold.org/en/stable", None), } -print(f"loading configurations for {project} {version} ...", file=sys.stderr) \ No newline at end of file +print(f"loading configurations for {project} {version} ...", file=sys.stderr) + +# -- Biocsetup configuration ------------------------------------------------- + +# Enable execution of code chunks in markdown +extensions.append('myst_nb') + +# Less verbose api documentation +extensions.append('sphinx_autodoc_typehints') + +autodoc_default_options = { + "special-members": True, + "undoc-members": True, + "exclude-members": "__weakref__, __dict__, __str__, __module__", +} + +autosummary_generate = True +autosummary_imported_members = True diff --git a/docs/requirements.txt b/docs/requirements.txt index 0990c2a..6d65a9b 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,3 +1,4 @@ +furo # Requirements file for ReadTheDocs, check .readthedocs.yml. # To build the module reference correctly, make sure every external package # under `install_requires` in `setup.cfg` is also listed here! diff --git a/src/biocsetup/cli.py b/src/biocsetup/cli.py index 434b6be..00f91ac 100644 --- a/src/biocsetup/cli.py +++ b/src/biocsetup/cli.py @@ -9,10 +9,10 @@ @click.command() @click.argument("project_path") -@click.option("--description", "-d", help="Project description") +@click.option("--description", "-d", help="Project description", default="Add a short description here!") @click.option("--license", "-l", default="MIT", help="License (default: MIT)") def main(project_path: str, description: str, license: str): - """Create a new Python package repository with consistent configuration.""" + """Create a new BiocPy Python package.""" create_repository( project_path=project_path, description=description, diff --git a/src/biocsetup/create_repository.py b/src/biocsetup/create_repository.py index b198606..9eacdd0 100644 --- a/src/biocsetup/create_repository.py +++ b/src/biocsetup/create_repository.py @@ -2,7 +2,7 @@ from pathlib import Path from typing import Optional -from pyscaffold import api +from pyscaffold import api, file_system, shell from pyscaffoldext.markdown.extension import Markdown __author__ = "Jayaram Kancherla" @@ -12,7 +12,7 @@ def create_repository( project_path: str, - description: Optional[str] = None, + description: Optional[str] = "Add a short description here!", license: str = "MIT", ) -> None: """ @@ -20,23 +20,29 @@ def create_repository( Args: project_path: - Path where the new project should be created + Path where the new project should be created. description: - Optional project description + Optional project description. license: - License to use (default: MIT) + License to use. + Defaults to 'MIT'. """ # Create project using pyscaffold with markdown extension + if description is None: + description = "Add a short description here!" + opts = { "project_path": project_path, - "description": description or "Add a short description here!", + "description": description, "license": license, "extensions": [Markdown()], } api.create_project(**opts) + modified_files = [] + # Get absolute path to templates directory template_dir = Path(__file__).parent / "templates" @@ -48,11 +54,13 @@ def create_repository( src = template_dir / "github_workflows" / workflow dst = gh_actions_dir / workflow shutil.copy2(src, dst) + modified_files.append(dst) # Add pre-commit config precommit_src = template_dir / "precommit" / "pre-commit-config.yaml" precommit_dst = Path(project_path) / ".pre-commit-config.yaml" shutil.copy2(precommit_src, precommit_dst) + modified_files.append(precommit_dst) # Modify sphinx conf.py conf_py_path = Path(project_path) / "docs" / "conf.py" @@ -61,6 +69,7 @@ def create_repository( # Add myst-nb extension and configuration myst_config = """ + # -- Biocsetup configuration ------------------------------------------------- # Enable execution of code chunks in markdown @@ -77,24 +86,25 @@ def create_repository( autosummary_generate = True autosummary_imported_members = True - -html_theme = "furo" """ + conf_content = conf_content.replace("alabaster", "furo") + with open(conf_py_path, "w") as f: f.write(conf_content + myst_config) + modified_files.append(conf_py_path) # Update requirements.txt for docs docs_requirements = Path(project_path) / "docs" / "requirements.txt" with open(docs_requirements, "a") as f: - f.write("\nmyst-nb\nfuro\nsphinx-autodoc-typehints\n") + f.write("myst-nb\nfuro\nsphinx-autodoc-typehints\n") + modified_files.append(docs_requirements) # Modify README readme_path = Path(project_path) / "README.md" proj_name = Path(project_path).parts[-1] - new_readme = f""" -[![PyPI-Server](https://img.shields.io/pypi/v/{proj_name}.svg)](https://pypi.org/project/{proj_name}/) + new_readme = f"""[![PyPI-Server](https://img.shields.io/pypi/v/{proj_name}.svg)](https://pypi.org/project/{proj_name}/) ![Unit tests](https://github.com/BiocPy/{proj_name}/actions/workflows/pypi-test.yml/badge.svg) # {proj_name} @@ -121,6 +131,7 @@ def create_repository( with open(readme_path, "w") as f: f.write(new_readme) + modified_files.append(readme_path) # Modify ppyproject.toml to add ruff configuration pyprj_path = Path(project_path) / "pyproject.toml" @@ -147,3 +158,12 @@ def create_repository( with open(pyprj_path, "w") as f: f.write(pyprj_content + ruff_config) + modified_files.append(pyprj_path) + + with file_system.chdir(project_path): + for f in modified_files: + shell.git("add", str(f.relative_to(project_path))) + + shell.git("commit", "-m", "BiocSetup configuration") + + print("BiocSetup complete! 🚀 💥") diff --git a/tests/test_cli.py b/tests/test_cli.py index 58bc6d7..a61aaaa 100644 --- a/tests/test_cli.py +++ b/tests/test_cli.py @@ -66,6 +66,6 @@ def test_cli_help(): runner = CliRunner() result = runner.invoke(main, ["--help"]) assert result.exit_code == 0 - assert "Create a new Python package repository" in result.output + assert "Create a new BiocPy Python package" in result.output assert "--description" in result.output assert "--license" in result.output