From 79f2082b583a1dd355faa19e45345fdbe39061e2 Mon Sep 17 00:00:00 2001 From: Domenic Fiore Date: Sat, 13 Jul 2024 21:29:05 -0400 Subject: [PATCH 1/3] Documentation start --- mkdocs.yaml | 74 ++++++++++++++++++++++++++++++++++++++++++++++ perdoo/__init__.py | 30 +++++++++++++++++++ pyproject.toml | 6 ++++ 3 files changed, 110 insertions(+) create mode 100644 mkdocs.yaml diff --git a/mkdocs.yaml b/mkdocs.yaml new file mode 100644 index 0000000..0093235 --- /dev/null +++ b/mkdocs.yaml @@ -0,0 +1,74 @@ +site_name: Perdoo +site_url: https://perdoo.readthedocs.io/en/latest/ +site_description: A Python application to help sort and organize your comic collection. +site_author: Jonah Jackson + +copyright: GPL-3.0 + +repo_url: https://github.com/Buried-In-Code/Perdoo +repo_name: Buried-In-Code/Perdoo + +theme: + name: material + favicon: img/favicon.ico + features: + - content.code.copy + - navigation.expand + - navigation.top + icon: + repo: material/github + palette: + - media: "(prefers-color-scheme: light)" + scheme: default + primary: teal + toggle: + icon: material/weather-sunny + name: Switch to dark mode + - media: "(prefers-color-scheme: dark)" + scheme: slate + primary: teal + toggle: + icon: material/weather-night + name: Switch to light mode + +extra: + social: + - icon: material/github + link: https://github.com/Buried-In-Code + - icon: material/mastodon + link: https://fosstodon.org/@BuriedInCode + - icon: simple/matrix + link: https://matrix.to/#/#The-Dev-Environment:matrix.org + +markdown_extensions: + - pymdownx.highlight: + auto_title: true + - pymdownx.inlinehilite + - pymdownx.superfences + + +nav: + - Home: index.md + - perdoo: + - Package: perdoo/__init__.md + - exceptions: perdoo/exceptions.md + +plugins: + - search + - mkdocstrings: + default_handler: python + handlers: + python: + options: + show_root_heading: True + show_root_full_path: False + show_category_heading: True + # Docstrings + docstring_style: google + docstring_section_style: spacy + line_length: 100 + merge_init_into_class: True + show_signature_annotations: True + # Additional + show_source: False + - include-markdown diff --git a/perdoo/__init__.py b/perdoo/__init__.py index 8ae966d..28b74ef 100644 --- a/perdoo/__init__.py +++ b/perdoo/__init__.py @@ -1,3 +1,5 @@ +"""Perdoo entry file.""" + __all__ = [ "__version__", "ARCHIVE_EXTENSIONS", @@ -23,6 +25,12 @@ def get_cache_dir() -> Path: + """Create and return the path to the cache for Perdoo, supports XDG_CACHE_HOME environment + variable. + + Returns: + The path to the Perdoo cache folder. + """ cache_home = os.getenv("XDG_CACHE_HOME", default=str(Path.home() / ".cache")) folder = Path(cache_home).resolve() / "perdoo" folder.mkdir(exist_ok=True, parents=True) @@ -30,6 +38,12 @@ def get_cache_dir() -> Path: def get_config_dir() -> Path: + """Create and return the path to the config directory for Perdoo, supports XDG_CONFIG_HOME + environment variable. + + Returns: + The path to the Perdoo configuration folder. + """ config_home = os.getenv("XDG_CONFIG_HOME", default=str(Path.home() / ".config")) folder = Path(config_home).resolve() / "perdoo" folder.mkdir(exist_ok=True, parents=True) @@ -37,6 +51,12 @@ def get_config_dir() -> Path: def get_data_dir() -> Path: + """Create and return the path to the data directory for Perdoo, supports XDG_DATA_HOME + environment variable. + + Returns: + The path to the Perdoo data folder. + """ data_home = os.getenv("XDG_DATA_HOME", default=str(Path.home() / ".local" / "share")) folder = Path(data_home).resolve() / "perdoo" folder.mkdir(exist_ok=True, parents=True) @@ -44,10 +64,20 @@ def get_data_dir() -> Path: def get_project_dir() -> Path: + """Returns the directory in which Perdoo is installed. + + Returns: + The path to the Perdoo installation folder. + """ return Path(__file__).parent.parent def setup_logging(debug: bool = False) -> None: + """Sets up logging for the Perdoo application. + + Args: + debug (bool, optional): Whether to enable debug logging. + """ install(show_locals=True, max_frames=6, console=CONSOLE) log_folder = get_project_dir() / "logs" log_folder.mkdir(parents=True, exist_ok=True) diff --git a/pyproject.toml b/pyproject.toml index a62b57a..fb07bed 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -51,6 +51,12 @@ requires-python = ">= 3.8" cb7 = [ "py7zr >= 0.21.1" ] +docs = [ + "mkdocs >= 1.6.0", + "mkdocs-include-markdown-plugin >= 6.2.1", + "mkdocs-material >= 9.5.27", + "mkdocstrings[python] >= 0.25.1" +] [project.scripts] Perdoo = "perdoo.__main__:main" From c68e0be51cd9f92cdf00a3ad435f50ef9b420b63 Mon Sep 17 00:00:00 2001 From: Domenic Fiore Date: Sat, 13 Jul 2024 21:56:29 -0400 Subject: [PATCH 2/3] Set up mkdocs --- .gitignore | 150 +++++++++++++++++++++++++++++++++++++--- .readthedocs.yaml | 22 ++++++ docs/index.md | 3 + docs/perdoo/__init__.md | 7 ++ mkdocs.yaml | 1 - requirements-dev.lock | 104 +++++++++++++++++++++++++++- requirements.lock | 110 +++++++++++++++++++++++++++-- 7 files changed, 378 insertions(+), 19 deletions(-) create mode 100644 .readthedocs.yaml create mode 100644 docs/index.md create mode 100644 docs/perdoo/__init__.md diff --git a/.gitignore b/.gitignore index c15d3fe..d0030d2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,16 +1,146 @@ -# =====Folders===== +# Byte-compiled / optimized / DLL files __pycache__/ -__pypackages__/ -.idea/ -.ruff_cache/ -.venv/ +*.py[cod] +*$py.class + +# C extensions +*.so + +# Distribution / packaging +.Python build/ +develop-eggs/ dist/ -logs/ +downloads/ +eggs/ +.eggs/ +lib/ +lib64/ +parts/ +sdist/ +var/ +wheels/ +share/python-wheels/ +*.egg-info/ +.installed.cfg +*.egg +MANIFEST -# =====Files===== -*.iml -.python-version +# PyInstaller +# Usually these files are written by a python script from a template +# before PyInstaller builds the exe, so as to inject date/other infos into it. +*.manifest +*.spec + +# Installer logs +pip-log.txt +pip-delete-this-directory.txt + +# Unit test / coverage reports +htmlcov/ +.tox/ +.nox/ +.coverage +.coverage.* +.cache +nosetests.xml +coverage.xml +*.cover +*.py,cover +.hypothesis/ +.pytest_cache/ +cover/ + +# Translations +*.mo +*.pot + +# Django stuff: *.log +local_settings.py +db.sqlite3 +db.sqlite3-journal + +# Flask stuff: +instance/ +.webassets-cache + +# Scrapy stuff: +.scrapy + +# Sphinx documentation +docs/_build/ + +# PyBuilder +.pybuilder/ +target/ + +# Jupyter Notebook +.ipynb_checkpoints + +# IPython +profile_default/ +ipython_config.py + +# pyenv +.python-version -# =====Project===== +# pipenv +Pipfile.lock + +# poetry +poetry.lock + +# pdm +pdm.lock +.pdm.toml +.pdm-python + +# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +__pypackages__/ + +# Celery stuff +celerybeat-schedule +celerybeat.pid + +# SageMath parsed files +*.sage.py + +# Environments +.env +.venv +env/ +venv/ +ENV/ +env.bak/ +venv.bak/ + +# Spyder project settings +.spyderproject +.spyproject + +# Rope project settings +.ropeproject + +# mkdocs documentation +/site + +# mypy +.mypy_cache/ +.dmypy.json +dmypy.json + +# Pyre type checker +.pyre/ + +# pytype static type analyzer +.pytype/ + +# Cython debug symbols +cython_debug/ + +# PyCharm +.idea/ + +# Custom +.ruff_cache/ diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000..af2d66c --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,22 @@ +# Read the Docs configuration file for MkDocs projects +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the version of Python and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.12" + +mkdocs: + configuration: mkdocs.yaml + +# Optionally declare the Python requirements required to build your docs +python: + install: + - method: pip + path: . + extra_requirements: + - docs diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..768aab5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,3 @@ +{% +include-markdown "../README.md" +%} diff --git a/docs/perdoo/__init__.md b/docs/perdoo/__init__.md new file mode 100644 index 0000000..c92323c --- /dev/null +++ b/docs/perdoo/__init__.md @@ -0,0 +1,7 @@ +# Package Contents + +::: perdoo.get_cache_dir +::: perdoo.get_config_dir +::: perdoo.get_data_dir +::: perdoo.get_project_dir +::: perdoo.setup_logging diff --git a/mkdocs.yaml b/mkdocs.yaml index 0093235..6afa9ab 100644 --- a/mkdocs.yaml +++ b/mkdocs.yaml @@ -51,7 +51,6 @@ nav: - Home: index.md - perdoo: - Package: perdoo/__init__.md - - exceptions: perdoo/exceptions.md plugins: - search diff --git a/requirements-dev.lock b/requirements-dev.lock index de1b34b..c68f817 100644 --- a/requirements-dev.lock +++ b/requirements-dev.lock @@ -10,8 +10,15 @@ # universal: false -e file:. + # via file:///- annotated-types==0.7.0 # via pydantic +astunparse==1.6.3 + # via griffe +babel==2.15.0 + # via mkdocs-material +bracex==2.4 + # via wcmatch brotli==1.1.0 # via py7zr certifi==2024.7.4 @@ -20,32 +27,87 @@ cfgv==3.4.0 # via pre-commit charset-normalizer==3.3.2 # via requests +click==8.1.7 + # via mkdocs + # via mkdocstrings +colorama==0.4.6 + # via griffe + # via mkdocs-material distlib==0.3.8 # via virtualenv esak==1.3.2 # via perdoo -eval-type-backport==0.2.0 +eval-type-backport==0.2.0 ; python_version < "3.10" # via himon # via mokkari # via perdoo # via simyan filelock==3.15.4 # via virtualenv +ghp-import==2.1.0 + # via mkdocs +griffe==0.47.0 + # via mkdocstrings-python himon==0.6.1 # via perdoo identify==2.6.0 # via pre-commit idna==3.7 # via requests +importlib-metadata==8.0.0 + # via markdown + # via mkdocs + # via mkdocs-get-deps + # via mkdocstrings inflate64==1.0.0 # via py7zr +jinja2==3.1.4 + # via mkdocs + # via mkdocs-material + # via mkdocstrings +markdown==3.6 + # via mkdocs + # via mkdocs-autorefs + # via mkdocs-material + # via mkdocstrings + # via pymdown-extensions markdown-it-py==3.0.0 # via rich +markupsafe==2.1.5 + # via jinja2 + # via mkdocs + # via mkdocs-autorefs + # via mkdocstrings marshmallow==3.21.3 # via esak mdurl==0.1.2 # via markdown-it-py -mokkari @ git+https://github.com/Buried-In-Code/mokkari@e55697cb7eb0d52d206cd5df5af300752d86dd38 +mergedeep==1.3.4 + # via mkdocs + # via mkdocs-get-deps +mkdocs==1.6.0 + # via mkdocs-autorefs + # via mkdocs-include-markdown-plugin + # via mkdocs-material + # via mkdocstrings + # via perdoo +mkdocs-autorefs==1.0.1 + # via mkdocstrings +mkdocs-get-deps==0.2.0 + # via mkdocs +mkdocs-include-markdown-plugin==6.2.1 + # via perdoo +mkdocs-material==9.5.28 + # via perdoo +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocstrings==0.25.1 + # via mkdocstrings + # via mkdocstrings-python + # via perdoo +mkdocstrings-python==1.10.5 + # via mkdocstrings +mokkari @ git+https://github.com/Buried-In-Code/mokkari ; python_version < "3.10" # via perdoo multivolumefile==0.2.3 # via py7zr @@ -55,9 +117,16 @@ nodeenv==1.9.1 # via pre-commit packaging==24.1 # via marshmallow + # via mkdocs +paginate==0.5.6 + # via mkdocs-material +pathspec==0.12.1 + # via mkdocs pillow==10.4.0 # via perdoo platformdirs==4.2.2 + # via mkdocs-get-deps + # via mkdocstrings # via virtualenv pre-commit==3.5.0 psutil==6.0.0 @@ -76,11 +145,25 @@ pydantic==2.8.2 pydantic-core==2.20.1 # via pydantic pygments==2.18.0 + # via mkdocs-material # via rich +pymdown-extensions==10.8.1 + # via mkdocs-material + # via mkdocstrings pyppmd==1.1.0 # via py7zr +python-dateutil==2.9.0.post0 + # via ghp-import +pytz==2024.1 + # via babel pyyaml==6.0.1 + # via mkdocs + # via mkdocs-get-deps # via pre-commit + # via pymdown-extensions + # via pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs pyzstd==0.16.0 # via py7zr rarfile==4.2 @@ -89,23 +172,30 @@ ratelimit==2.2.1 # via himon # via mokkari # via simyan +regex==2024.5.15 + # via mkdocs-material requests==2.32.3 # via esak # via himon + # via mkdocs-material # via mokkari # via simyan rich==13.7.1 # via perdoo simyan==1.2.2 # via perdoo +six==1.16.0 + # via astunparse + # via python-dateutil texttable==1.7.0 # via py7zr -tomli==2.0.1 +tomli==2.0.1 ; python_version < "3.11" # via perdoo tomli-w==1.0.0 # via perdoo typing-extensions==4.12.2 # via annotated-types + # via mkdocstrings # via pydantic # via pydantic-core # via rich @@ -113,5 +203,13 @@ urllib3==2.2.2 # via requests virtualenv==20.26.3 # via pre-commit +watchdog==4.0.1 + # via mkdocs +wcmatch==8.5.2 + # via mkdocs-include-markdown-plugin +wheel==0.43.0 + # via astunparse xmltodict==0.13.0 # via perdoo +zipp==3.19.2 + # via importlib-metadata diff --git a/requirements.lock b/requirements.lock index c3b2889..a173de4 100644 --- a/requirements.lock +++ b/requirements.lock @@ -3,41 +3,103 @@ # # last locked with the following flags: # pre: false -# features: ["cb7"] -# all-features: false +# features: [] +# all-features: true # with-sources: false # generate-hashes: false # universal: false -e file:. + # via file:///- annotated-types==0.7.0 # via pydantic +astunparse==1.6.3 + # via griffe +babel==2.15.0 + # via mkdocs-material +bracex==2.4 + # via wcmatch brotli==1.1.0 # via py7zr certifi==2024.7.4 # via requests charset-normalizer==3.3.2 # via requests +click==8.1.7 + # via mkdocs + # via mkdocstrings +colorama==0.4.6 + # via griffe + # via mkdocs-material esak==1.3.2 # via perdoo -eval-type-backport==0.2.0 +eval-type-backport==0.2.0 ; python_version < "3.10" # via himon # via mokkari # via perdoo # via simyan +ghp-import==2.1.0 + # via mkdocs +griffe==0.47.0 + # via mkdocstrings-python himon==0.6.1 # via perdoo idna==3.7 # via requests +importlib-metadata==8.0.0 + # via markdown + # via mkdocs + # via mkdocs-get-deps + # via mkdocstrings inflate64==1.0.0 # via py7zr +jinja2==3.1.4 + # via mkdocs + # via mkdocs-material + # via mkdocstrings +markdown==3.6 + # via mkdocs + # via mkdocs-autorefs + # via mkdocs-material + # via mkdocstrings + # via pymdown-extensions markdown-it-py==3.0.0 # via rich +markupsafe==2.1.5 + # via jinja2 + # via mkdocs + # via mkdocs-autorefs + # via mkdocstrings marshmallow==3.21.3 # via esak mdurl==0.1.2 # via markdown-it-py -mokkari @ git+https://github.com/Buried-In-Code/mokkari@e55697cb7eb0d52d206cd5df5af300752d86dd38 +mergedeep==1.3.4 + # via mkdocs + # via mkdocs-get-deps +mkdocs==1.6.0 + # via mkdocs-autorefs + # via mkdocs-include-markdown-plugin + # via mkdocs-material + # via mkdocstrings + # via perdoo +mkdocs-autorefs==1.0.1 + # via mkdocstrings +mkdocs-get-deps==0.2.0 + # via mkdocs +mkdocs-include-markdown-plugin==6.2.1 + # via perdoo +mkdocs-material==9.5.28 + # via perdoo +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocstrings==0.25.1 + # via mkdocstrings + # via mkdocstrings-python + # via perdoo +mkdocstrings-python==1.10.5 + # via mkdocstrings +mokkari @ git+https://github.com/Buried-In-Code/mokkari ; python_version < "3.10" # via perdoo multivolumefile==0.2.3 # via py7zr @@ -45,8 +107,16 @@ natsort==8.4.0 # via perdoo packaging==24.1 # via marshmallow + # via mkdocs +paginate==0.5.6 + # via mkdocs-material +pathspec==0.12.1 + # via mkdocs pillow==10.4.0 # via perdoo +platformdirs==4.2.2 + # via mkdocs-get-deps + # via mkdocstrings psutil==6.0.0 # via py7zr py7zr==0.21.1 @@ -63,9 +133,24 @@ pydantic==2.8.2 pydantic-core==2.20.1 # via pydantic pygments==2.18.0 + # via mkdocs-material # via rich +pymdown-extensions==10.8.1 + # via mkdocs-material + # via mkdocstrings pyppmd==1.1.0 # via py7zr +python-dateutil==2.9.0.post0 + # via ghp-import +pytz==2024.1 + # via babel +pyyaml==6.0.1 + # via mkdocs + # via mkdocs-get-deps + # via pymdown-extensions + # via pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs pyzstd==0.16.0 # via py7zr rarfile==4.2 @@ -74,27 +159,42 @@ ratelimit==2.2.1 # via himon # via mokkari # via simyan +regex==2024.5.15 + # via mkdocs-material requests==2.32.3 # via esak # via himon + # via mkdocs-material # via mokkari # via simyan rich==13.7.1 # via perdoo simyan==1.2.2 # via perdoo +six==1.16.0 + # via astunparse + # via python-dateutil texttable==1.7.0 # via py7zr -tomli==2.0.1 +tomli==2.0.1 ; python_version < "3.11" # via perdoo tomli-w==1.0.0 # via perdoo typing-extensions==4.12.2 # via annotated-types + # via mkdocstrings # via pydantic # via pydantic-core # via rich urllib3==2.2.2 # via requests +watchdog==4.0.1 + # via mkdocs +wcmatch==8.5.2 + # via mkdocs-include-markdown-plugin +wheel==0.43.0 + # via astunparse xmltodict==0.13.0 # via perdoo +zipp==3.19.2 + # via importlib-metadata From 0d72e29c13d84ee31cc306854162b7eacc7714da Mon Sep 17 00:00:00 2001 From: Domenic Fiore Date: Sun, 14 Jul 2024 19:51:40 -0400 Subject: [PATCH 3/3] Removed D from ruff ignore --- perdoo/__main__.py | 13 +++++++++++++ pyproject.toml | 1 - requirements-dev.lock | 2 +- requirements.lock | 2 +- 4 files changed, 15 insertions(+), 3 deletions(-) diff --git a/perdoo/__main__.py b/perdoo/__main__.py index c96cece..3be5e29 100644 --- a/perdoo/__main__.py +++ b/perdoo/__main__.py @@ -1,3 +1,5 @@ +"""Main Perdoo file containing general methods.""" + from __future__ import annotations import logging @@ -26,6 +28,11 @@ def parse_arguments() -> Namespace: + """Argument parser. + + Returns: + Namespace: A new namespace object with parsed arguments. + """ parser = ArgumentParser(prog="Perdoo", allow_abbrev=False) parser.version = __version__ parser.add_argument("--force", action="store_true") @@ -35,6 +42,12 @@ def parse_arguments() -> Namespace: def convert_collection(path: Path, output: OutputFormat) -> None: + """Converts comic archives contained within a given path. + + Args: + path (Path): Path to the directory containing comic archives. + output (OutputFormat): Comic archive output format. + """ format_, archive_type = { OutputFormat.CB7: (".cb7", CB7Archive), OutputFormat.CBT: (".cbt", CBTArchive), diff --git a/pyproject.toml b/pyproject.toml index fb07bed..445f462 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -88,7 +88,6 @@ skip-magic-trailing-comma = true ignore = [ "C901", "COM812", - "D", "D107", "DTZ", "EM101", diff --git a/requirements-dev.lock b/requirements-dev.lock index c68f817..ef168ea 100644 --- a/requirements-dev.lock +++ b/requirements-dev.lock @@ -97,7 +97,7 @@ mkdocs-get-deps==0.2.0 # via mkdocs mkdocs-include-markdown-plugin==6.2.1 # via perdoo -mkdocs-material==9.5.28 +mkdocs-material==9.5.29 # via perdoo mkdocs-material-extensions==1.3.1 # via mkdocs-material diff --git a/requirements.lock b/requirements.lock index a173de4..e213532 100644 --- a/requirements.lock +++ b/requirements.lock @@ -89,7 +89,7 @@ mkdocs-get-deps==0.2.0 # via mkdocs mkdocs-include-markdown-plugin==6.2.1 # via perdoo -mkdocs-material==9.5.28 +mkdocs-material==9.5.29 # via perdoo mkdocs-material-extensions==1.3.1 # via mkdocs-material