Setup a MkDocs automatic documentation

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

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.

docs/index.md

@@ -0,0 +1 @@
+--8<-- "README.md"

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

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"]

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

requirements.txt

@@ -1,3 +1,4 @@
 -e .
 -r requirements-dev.txt
 -r requirements-tests.txt
+-r requirements-docs.txt

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

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(