Create documentation

.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/

.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

docs/index.md

@@ -0,0 +1,3 @@
+{%
+include-markdown "../README.md"
+%}

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

mkdocs.yaml

@@ -0,0 +1,73 @@
+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
+
+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

perdoo/__init__.py

@@ -1,3 +1,5 @@
+"""Perdoo entry file."""
+
 __all__ = [
     "__version__",
     "ARCHIVE_EXTENSIONS",
@@ -23,31 +25,59 @@
 
 
 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)
     return folder
 
 
 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)
     return folder
 
 
 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)
     return folder
 
 
 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)

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),

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"
@@ -82,7 +88,6 @@ skip-magic-trailing-comma = true
 ignore = [
   "C901",
   "COM812",
-  "D",
   "D107",
   "DTZ",
   "EM101",