diff --git a/README.md b/README.md index ad3ce6d..69e5575 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,14 @@ # Knuckles -> A [Subsonic](https://subsonic.org/pages/index.jsp)/[OpenSubsonic](https://opensubsonic.netlify.app/) API wrapper for Python. +> A [OpenSubsonic](https://opensubsonic.netlify.app/) API wrapper for Python. -## Compatibility and scope -Knuckles **only** works with music servers compatible with the REST API version 1.4.0 (Subsonic 4.2). It follows strictly the [OpenSubsonic API Spec](https://opensubsonic.netlify.app/docs/opensubsonic-api/) **without** implementing any endpoint related to video media and the legacy non-ID3 file-based system. +## Compatiblity +Knuckles **only** works with servers compatible with the REST API version 1.4.0 onwards (Subsonic 4.2+). +It follows strictly the [OpenSubsonic API Spec](https://opensubsonic.netlify.app/docs/opensubsonic-api/), being fully retro-compatible with the original [Subsonic API](https://subsonic.org/pages/api.jsp). + +### Quickstart +... ## Acknowledgements Created with :heart: by [Jorge "Kutu" Dobón Blanco](https://dobon.dev). + +::: knuckles.models._user diff --git a/TODO.md b/TODO.md index 0d57aff..8b9b534 100644 --- a/TODO.md +++ b/TODO.md @@ -2,6 +2,7 @@ - [ ] Check and rewrite all docstrings taking care about raising exceptions. - [ ] Spin up a `MkDocs` documentation. - [ ] Add the URL in the GitHub page. +- [ ] Decide if use `Subsonic/OpenSubsonic`, `(Open)Subsonic` or `OpenSubsonic`. ## Implementation status The final objetive of Knuckles to be a fully compatible implementation wrapper around the [OpenSubsonic API Spec](https://opensubsonic.netlify.app/), a superset of the [Subsonic API Spec](https://subsonic.org/pages/api.jsp) that tries to improve and extend the API without breaking changes. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..612c7a5 --- /dev/null +++ b/docs/index.md @@ -0,0 +1 @@ +--8<-- "README.md" diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..ce13675 --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,33 @@ +site_name: Knuckles + +repo_url: https://github.com/kutu-dev/knuckles +repo_name: kutu-dev/knuckles + +theme: + name: material + features: + - navigation.tabs + +nav: + - Home: "index.md" + - Reference: "reference/" + +plugins: +- search +- gen-files: + scripts: + - scripts/generate-reference-pages.py +- literate-nav: + nav_file: summary.md +- mkdocstrings: + handlers: + python: + options: + docstring_options: + ignore_init_summary: true + show_if_no_docstring: true + merge_init_into_class: true + +markdown_extensions: + - pymdownx.snippets + - pymdownx.emoji diff --git a/pyproject.toml b/pyproject.toml index 6c61292..8a22cf0 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -14,12 +14,21 @@ dev = [ "mypy>=1.4.1", "types-requests>=2.31.0.1", "types-python-dateutil>=2.8.19.14", - "pre-commit>=3.7.0" + "pre-commit>=3.7.0", + "pip-tools>=7.4.1" ] tests = [ "pytest>=7.4.0", "responses>=0.23.1", ] +docs = [ + "mkdocs==1.5.3", + "mkdocs-material==9.5.18", + "mkdocstrings[python]==0.24.3", + "mkdocs-gen-files==0.5.0", + "pymdown-extensions==10.8.0", + "mkdocs-literate-nav==0.6.1" +] [build-system] requires = ["setuptools"] diff --git a/requirements-docs.txt b/requirements-docs.txt new file mode 100644 index 0000000..2de24ca --- /dev/null +++ b/requirements-docs.txt @@ -0,0 +1,110 @@ +# +# This file is autogenerated by pip-compile with Python 3.11 +# by the following command: +# +# pip-compile --extra=docs --output-file=requirements-docs.txt pyproject.toml +# +babel==2.14.0 + # via mkdocs-material +certifi==2024.2.2 + # via requests +charset-normalizer==3.3.2 + # via requests +click==8.1.7 + # via + # mkdocs + # mkdocstrings +colorama==0.4.6 + # via + # griffe + # mkdocs-material +ghp-import==2.1.0 + # via mkdocs +griffe==0.44.0 + # via mkdocstrings-python +idna==3.7 + # via requests +jinja2==3.1.3 + # via + # mkdocs + # mkdocs-material + # mkdocstrings +markdown==3.6 + # via + # mkdocs + # mkdocs-autorefs + # mkdocs-material + # mkdocstrings + # pymdown-extensions +markupsafe==2.1.5 + # via + # jinja2 + # mkdocs + # mkdocs-autorefs + # mkdocstrings +mergedeep==1.3.4 + # via mkdocs +mkdocs==1.5.3 + # via + # knuckles (pyproject.toml) + # mkdocs-autorefs + # mkdocs-gen-files + # mkdocs-literate-nav + # mkdocs-material + # mkdocstrings +mkdocs-autorefs==1.0.1 + # via mkdocstrings +mkdocs-gen-files==0.5.0 + # via knuckles (pyproject.toml) +mkdocs-literate-nav==0.6.1 + # via knuckles (pyproject.toml) +mkdocs-material==9.5.18 + # via knuckles (pyproject.toml) +mkdocs-material-extensions==1.3.1 + # via mkdocs-material +mkdocstrings[python]==0.24.3 + # via + # knuckles (pyproject.toml) + # mkdocstrings-python +mkdocstrings-python==1.10.0 + # via mkdocstrings +packaging==24.0 + # via mkdocs +paginate==0.5.6 + # via mkdocs-material +pathspec==0.12.1 + # via mkdocs +platformdirs==4.2.0 + # via + # mkdocs + # mkdocstrings +pygments==2.17.2 + # via mkdocs-material +pymdown-extensions==10.8 + # via + # knuckles (pyproject.toml) + # mkdocs-material + # mkdocstrings +python-dateutil==2.9.0.post0 + # via + # ghp-import + # knuckles (pyproject.toml) +pyyaml==6.0.1 + # via + # mkdocs + # pymdown-extensions + # pyyaml-env-tag +pyyaml-env-tag==0.1 + # via mkdocs +regex==2024.4.16 + # via mkdocs-material +requests==2.31.0 + # via + # knuckles (pyproject.toml) + # mkdocs-material +six==1.16.0 + # via python-dateutil +urllib3==2.2.1 + # via requests +watchdog==4.0.0 + # via mkdocs diff --git a/requirements.txt b/requirements.txt index b58dba1..8e71c17 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,4 @@ -e . -r requirements-dev.txt -r requirements-tests.txt +-r requirements-docs.txt diff --git a/scripts/generate-reference-pages.py b/scripts/generate-reference-pages.py new file mode 100644 index 0000000..3a57939 --- /dev/null +++ b/scripts/generate-reference-pages.py @@ -0,0 +1,45 @@ +"""Generate the code reference pages. +Modified script from the `mkdocstrings` documentation: + https://mkdocstrings.github.io/recipes/#automatic-code-reference-pages +""" + +from pathlib import Path + +import mkdocs_gen_files + +nav = mkdocs_gen_files.Nav() + +root = Path(__file__).parent.parent +src = root / "src" + +for path in sorted(src.rglob("*.py")): + relative_source_path = path.relative_to(src) + + module_path = relative_source_path.with_suffix("") + module_name = module_path.parts[-1] + + if module_name == "__init__" or module_name == "__main__": + continue + + # Remove the package name from the path + relative_docs_path = relative_source_path.relative_to(relative_source_path.parts[0]) + + titlecase_name = relative_docs_path.stem.title().strip("_").replace("_", " ") + titlecase_docs_path = Path(relative_docs_path.parent, f"{titlecase_name}.md") + + full_doc_path = Path("reference", titlecase_docs_path) + + # Make title case the section nav names + nav_route_path = tuple( + map(lambda nav_path: nav_path.title(), full_doc_path.parent.parts) + ) + nav[(*nav_route_path, titlecase_name)] = titlecase_docs_path.as_posix() + + with mkdocs_gen_files.open(full_doc_path, "w") as fd: + identifier = ".".join(module_path.parts) + print(f"::: {identifier}", file=fd) + + mkdocs_gen_files.set_edit_path(full_doc_path, path.relative_to(root)) + +with mkdocs_gen_files.open("reference/summary.md", "w") as nav_file: + nav_file.writelines(nav.build_literate_nav()) diff --git a/src/knuckles/_subsonic.py b/src/knuckles/_subsonic.py index 56082c8..52bdade 100644 --- a/src/knuckles/_subsonic.py +++ b/src/knuckles/_subsonic.py @@ -17,7 +17,7 @@ class Subsonic: - """The main class of the package, is used to interact with a Subsonic API.""" + """Container of all the methods to interact with the OpenSubsonic API""" def __init__( self, @@ -29,22 +29,16 @@ def __init__( use_token: bool = True, request_method: RequestMethod = RequestMethod.POST, ) -> None: - """The main class of the package, is used to interact with a Subsonic API. + """FF - :param url: The url of the Subsonic server. - :type url: str - :param user: The user to authenticate with - :type user: str - :param password: The password to authenticate with - :type password: str - :param client: A unique string identifying the client application. - :type client: str - :param use_https: If the requests should be sent using HTTPS, - defaults to True - :type use_https: bool, optional - :param use_token: If the connection should send to the server the clean password - or encode it in a token with a random salt, defaults to True - :type use_token: bool, optional + Args: + url: The URL of the Subsonic server to connect to. + user: The name of the user + password: asd + client: sad + use_https: d a + use_token: as + request_method: as """ self.api = Api( diff --git a/src/knuckles/models/__init__.py b/src/knuckles/models/__init__.py new file mode 100644 index 0000000..e69de29