diff --git a/docs/conf.py b/docs/conf.py index 81edb15..c2231c5 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -14,13 +14,18 @@ release = "0.2.1" # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration -extensions = ["sphinx.ext.duration", "autoapi.extension"] +extensions = [ + "myst_parser", + "sphinx.ext.duration", + "autoapi.extension" +] templates_path = ["_templates"] exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # -- AutoAPI Options --------------------------------------------------------- autoapi_dirs = ["../findmy/"] +autoapi_add_toctree_entry = False autoapi_options = [ "members", "undoc-members", @@ -33,5 +38,5 @@ autoapi_options = [ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = "alabaster" +html_theme = "furo" html_static_path = ["_static"] diff --git a/docs/getstarted/account.md b/docs/getstarted/account.md new file mode 100644 index 0000000..2835f0b --- /dev/null +++ b/docs/getstarted/account.md @@ -0,0 +1,5 @@ +# Logging in + +Some useful features of this library require an active login session with Apple in order to work correctly. +That's because the remote endpoints require authentication to actually retrieve data. +This page will guide you through the steps needed to log into an Apple account using FindMy.py. diff --git a/docs/getstarted/index.md b/docs/getstarted/index.md new file mode 100644 index 0000000..60bc24b --- /dev/null +++ b/docs/getstarted/index.md @@ -0,0 +1,10 @@ +# Getting Started + +* * * + +```{toctree} +:maxdepth: 1 +:glob: + +* +``` \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..3cbf821 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,33 @@ +# FindMy.py + += 🍏 + 🎯 + 🐍! + +FindMy.py is a Python library aiming to provide everything you need +to interact with **Apple's FindMy Network**. +Its primary aims are feature completeness, reliability and elegant API design. +It abstracts all the heavy lifting away, while keeping the control flow in your hands. + +## Jump To + +[//]: # (This is hidden to prevent it from showing on the home page) +```{toctree} +:hidden: + +Home +``` + +[//]: # (Documentation can be expanded to maxdepth 2) +```{toctree} +:maxdepth: 2 + +getstarted/index +technical/index +``` + +[//]: # (Show these with a maxdepth of 1) +```{toctree} +:maxdepth: 1 + +API Reference +genindex +``` diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 6adf9ee..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. FindMy.py documentation master file, created by - sphinx-quickstart on Tue Jan 2 21:16:55 2024. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - -Welcome to FindMy.py's documentation! -===================================== - -.. toctree:: - :maxdepth: 2 - :caption: Contents: - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` diff --git a/docs/technical/1-Network.md b/docs/technical/1-Network.md new file mode 100644 index 0000000..3c2ff43 --- /dev/null +++ b/docs/technical/1-Network.md @@ -0,0 +1,2 @@ +# Overview of the Network + diff --git a/docs/technical/index.md b/docs/technical/index.md new file mode 100644 index 0000000..3f48b28 --- /dev/null +++ b/docs/technical/index.md @@ -0,0 +1,17 @@ +# Technical Documentation + +This category serves as a place to provide technical documentation about the Find My network. +More specifically, it serves as a technical reference for how certain features in this +library have been implemented. + +Most of the knowledge in this section has been sourced from other genius minds. +Make sure to check out the references section on the specific pages to read more about the topics. + +* * * + +```{toctree} +:maxdepth: 1 +:glob: + +* +``` diff --git a/poetry.lock b/poetry.lock index c78d880..3dd32d3 100644 --- a/poetry.lock +++ b/poetry.lock @@ -675,6 +675,23 @@ files = [ {file = "frozenlist-1.4.1.tar.gz", hash = "sha256:c037a86e8513059a2613aaba4d817bb90b9d9b6b69aace3ce9c877e8c8ed402b"}, ] +[[package]] +name = "furo" +version = "2024.1.29" +description = "A clean customisable Sphinx documentation theme." +optional = false +python-versions = ">=3.8" +files = [ + {file = "furo-2024.1.29-py3-none-any.whl", hash = "sha256:3548be2cef45a32f8cdc0272d415fcb3e5fa6a0eb4ddfe21df3ecf1fe45a13cf"}, + {file = "furo-2024.1.29.tar.gz", hash = "sha256:4d6b2fe3f10a6e36eb9cc24c1e7beb38d7a23fc7b3c382867503b7fcac8a1e02"}, +] + +[package.dependencies] +beautifulsoup4 = "*" +pygments = ">=2.7" +sphinx = ">=6.0,<8.0" +sphinx-basic-ng = "*" + [[package]] name = "identify" version = "2.5.33" @@ -747,6 +764,30 @@ MarkupSafe = ">=2.0" [package.extras] i18n = ["Babel (>=2.7)"] +[[package]] +name = "markdown-it-py" +version = "3.0.0" +description = "Python port of markdown-it. Markdown parsing, done right!" +optional = false +python-versions = ">=3.8" +files = [ + {file = "markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb"}, + {file = "markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1"}, +] + +[package.dependencies] +mdurl = ">=0.1,<1.0" + +[package.extras] +benchmarking = ["psutil", "pytest", "pytest-benchmark"] +code-style = ["pre-commit (>=3.0,<4.0)"] +compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "mistletoe (>=1.0,<2.0)", "mistune (>=2.0,<3.0)", "panflute (>=2.3,<3.0)"] +linkify = ["linkify-it-py (>=1,<3)"] +plugins = ["mdit-py-plugins"] +profiling = ["gprof2dot"] +rtd = ["jupyter_sphinx", "mdit-py-plugins", "myst-parser", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "sphinx_book_theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "markupsafe" version = "2.1.5" @@ -816,6 +857,36 @@ files = [ {file = "MarkupSafe-2.1.5.tar.gz", hash = "sha256:d283d37a890ba4c1ae73ffadf8046435c76e7bc2247bbb63c00bd1a709c6544b"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.4.0" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.8" +files = [ + {file = "mdit_py_plugins-0.4.0-py3-none-any.whl", hash = "sha256:b51b3bb70691f57f974e257e367107857a93b36f322a9e6d44ca5bf28ec2def9"}, + {file = "mdit_py_plugins-0.4.0.tar.gz", hash = "sha256:d8ab27e9aed6c38aa716819fedfde15ca275715955f8a185a8e1cf90fb1d2c1b"}, +] + +[package.dependencies] +markdown-it-py = ">=1.0.0,<4.0.0" + +[package.extras] +code-style = ["pre-commit"] +rtd = ["myst-parser", "sphinx-book-theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + +[[package]] +name = "mdurl" +version = "0.1.2" +description = "Markdown URL utilities" +optional = false +python-versions = ">=3.7" +files = [ + {file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"}, + {file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"}, +] + [[package]] name = "multidict" version = "6.0.5" @@ -915,6 +986,32 @@ files = [ {file = "multidict-6.0.5.tar.gz", hash = "sha256:f7e301075edaf50500f0b341543c41194d8df3ae5caf4702f2095f3ca73dd8da"}, ] +[[package]] +name = "myst-parser" +version = "2.0.0" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.8" +files = [ + {file = "myst_parser-2.0.0-py3-none-any.whl", hash = "sha256:7c36344ae39c8e740dad7fdabf5aa6fc4897a813083c6cc9990044eb93656b14"}, + {file = "myst_parser-2.0.0.tar.gz", hash = "sha256:ea929a67a6a0b1683cdbe19b8d2e724cd7643f8aa3e7bb18dd65beac3483bead"}, +] + +[package.dependencies] +docutils = ">=0.16,<0.21" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4,<1.0" +pyyaml = "*" +sphinx = ">=6,<8" + +[package.extras] +code-style = ["pre-commit (>=3.0,<4.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "pydata-sphinx-theme (==v0.13.0rc4)", "sphinx-autodoc2 (>=0.4.2,<0.5.0)", "sphinx-book-theme (==1.0.0rc2)", "sphinx-copybutton", "sphinx-design2", "sphinx-pyscript", "sphinx-tippy (>=0.3.1)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.8.2,<0.9.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=7,<8)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=7,<8)", "pytest-param-files (>=0.3.4,<0.4.0)"] + [[package]] name = "nodeenv" version = "1.8.0" @@ -1280,6 +1377,23 @@ sphinx = ">=6.1.0" [package.extras] docs = ["furo", "sphinx", "sphinx-design"] +[[package]] +name = "sphinx-basic-ng" +version = "1.0.0b2" +description = "A modern skeleton for Sphinx themes." +optional = false +python-versions = ">=3.7" +files = [ + {file = "sphinx_basic_ng-1.0.0b2-py3-none-any.whl", hash = "sha256:eb09aedbabfb650607e9b4b68c9d240b90b1e1be221d6ad71d61c52e29f7932b"}, + {file = "sphinx_basic_ng-1.0.0b2.tar.gz", hash = "sha256:9ec55a47c90c8c002b5960c57492ec3021f5193cb26cebc2dc4ea226848651c9"}, +] + +[package.dependencies] +sphinx = ">=4.0" + +[package.extras] +docs = ["furo", "ipython", "myst-parser", "sphinx-copybutton", "sphinx-inline-tabs"] + [[package]] name = "sphinxcontrib-applehelp" version = "1.0.8" @@ -1778,4 +1892,4 @@ scan = ["bleak"] [metadata] lock-version = "2.0" python-versions = ">=3.9,<3.13" -content-hash = "696a56ccbba231e3ec702aaee911977819b996d21074b37807c42a45d107c7ab" +content-hash = "ac0ef4ca30b86c4ef5b45db550b69e6ef85203e9c667cc5002ae8998cd05edd6" diff --git a/pyproject.toml b/pyproject.toml index 02c3e8e..773b4b1 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -22,6 +22,8 @@ pre-commit = "^3.6.0" sphinx = "^7.2.6" sphinx-autoapi = "^3.0.0" pyright = "^1.1.350" +furo = "^2024.1.29" +myst-parser = "^2.0.0" [tool.pyright] venvPath = "."