From ef14979e8c17d2045e85c83e9798aef8e61832d3 Mon Sep 17 00:00:00 2001 From: geo-martino Date: Fri, 12 Jan 2024 20:32:19 -0500 Subject: [PATCH] reformat reference documentation layout --- .github/workflows/documentation.yml | 6 +- docs/_static/style.css | 3 + docs/_templates/autosummary/base.rst | 5 ++ docs/_templates/autosummary/class.rst | 47 ++++++++++++++ docs/_templates/autosummary/module.rst | 80 +++++++++++++++++++++++ docs/_templates/module.rst_t | 29 +++++++++ docs/_templates/package.rst_t | 90 ++++++++++++++++++++++++++ docs/_templates/toc.rst_t | 9 +++ docs/conf.py | 48 ++++++++++++-- docs/index.rst | 16 ++--- pyproject.toml | 2 + src/syncify/spotify/api/api.py | 4 +- src/syncify/spotify/api/base.py | 3 +- 13 files changed, 322 insertions(+), 20 deletions(-) create mode 100644 docs/_static/style.css create mode 100644 docs/_templates/autosummary/base.rst create mode 100644 docs/_templates/autosummary/class.rst create mode 100644 docs/_templates/autosummary/module.rst create mode 100644 docs/_templates/module.rst_t create mode 100644 docs/_templates/package.rst_t create mode 100644 docs/_templates/toc.rst_t diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ebfd9de4..5e8a614e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -41,13 +41,17 @@ jobs: - name: Setup Pages uses: actions/configure-pages@v4 + - name: Install dependencies + run: | + sudo apt install graphviz + - name: Install module run: | pip install -e '.[docs]' - name: Sphinx build run: | - sphinx-apidoc -o ./docs ./src/syncify + sphinx-apidoc -o ./docs ./src/syncify -f -d 2 -M make html - name: Upload artifact diff --git a/docs/_static/style.css b/docs/_static/style.css new file mode 100644 index 00000000..90a4e2bd --- /dev/null +++ b/docs/_static/style.css @@ -0,0 +1,3 @@ +.wy-nav-content { + max-width: 1200px !important; +} \ No newline at end of file diff --git a/docs/_templates/autosummary/base.rst b/docs/_templates/autosummary/base.rst new file mode 100644 index 00000000..b7556ebf --- /dev/null +++ b/docs/_templates/autosummary/base.rst @@ -0,0 +1,5 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. auto{{ objtype }}:: {{ objname }} diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 00000000..a5903ce9 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,47 @@ +{%- set is_root = basename == project -%} +{%- set module_footer = ["base", "exception"] -%} +{%- set module_caps = ["api", "m3u", "xautopf", "flac", "mp3", "m4a", "wma"] -%} + +{%- macro formatname(name) -%} + {%- if name.endswith(".exception") -%} + {%- set name = "exceptions"-%} + {%- else -%} + {%- set name = name.replace("syncify.", "").split(".") | last -%} + {%- endif -%} + + {%- if name | lower in module_caps -%} + {{- name | upper -}} + {%- else -%} + {{- name | title -}} + {%- endif -%} +{%- endmacro -%} + +{{ formatname(fullname) | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + + {%- block methods -%} + .. automethod:: __init__ + + {%- if methods -%} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + {%- for item in methods -%} + ~{{ name }}.{{ item }} + {%- endfor %} + {%- endif -%} + {%- endblock -%} + + {%- block attributes -%} + {%- if attributes -%} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + {%- for item in attributes -%} + ~{{ name }}.{{ item }} + {%- endfor %} + {%- endif -%} + {%- endblock -%} diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 00000000..72f9f963 --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,80 @@ +{%- set is_root = basename == project -%} +{%- set module_footer = ["base", "exception"] -%} +{%- set module_caps = ["api", "m3u", "xautopf", "flac", "mp3", "m4a", "wma"] -%} + +{%- macro formatname(name) -%} + {%- if name.endswith(".exception") -%} + {%- set name = "exceptions"-%} + {%- else -%} + {%- set name = name.replace("syncify.", "").split(".") | last -%} + {%- endif -%} + + {%- if name | lower in module_caps -%} + {{- name | upper -}} + {%- else -%} + {{- name | title -}} + {%- endif -%} +{%- endmacro -%} + +{{ formatname(fullname) | escape | underline}} + +{% if classes -%} +.. inheritance-diagram:: {{ fullname }} + :parts: 1 +{%- endif %} + +.. automodule:: {{ fullname }} + + {%- block attributes -%} + {%- if attributes -%} + .. rubric:: {{ _('Module Attributes') }} + + .. autosummary:: + {% for item in attributes %} + {{ item }} + {%- endfor -%} + {%- endif -%} + {% endblock %} + + {% block functions -%} + {% if functions -%} + .. rubric:: {{ _('Functions') }} + .. autosummary:: + {% for item in functions %} + {{ item }} + {%- endfor -%} + {%- endif -%} + {% endblock %} + + {% block classes -%} + {% if classes -%} + .. rubric:: {{ _('Classes') }} + .. autosummary:: + {% for item in classes %} + {{ item }} + {%- endfor -%} + {%- endif -%} + {% endblock %} + + {% block exceptions -%} + {% if exceptions -%} + .. rubric:: {{ _('Exceptions') }} + .. autosummary:: + {% for item in exceptions %} + {{ item }} + {%- endfor -%} + {%- endif -%} + {%- endblock %} + +{%- block modules -%} +{%- if modules %} +.. rubric:: Modules + +.. autosummary:: + :toctree: + :recursive: +{% for item in modules %} + {{ item }} +{% endfor %} +{% endif %} +{% endblock %} diff --git a/docs/_templates/module.rst_t b/docs/_templates/module.rst_t new file mode 100644 index 00000000..1220fcfc --- /dev/null +++ b/docs/_templates/module.rst_t @@ -0,0 +1,29 @@ +{%- set is_root = basename == project -%} +{%- set module_footer = ["base", "exception"] -%} +{%- set module_caps = ["api", "m3u", "xautopf", "flac", "mp3", "m4a", "wma"] -%} + +{%- macro formatname(name) -%} + {%- if name.endswith(".exception") -%} + {%- set name = "exceptions"-%} + {%- else -%} + {%- set name = name.replace("syncify.", "").split(".") | last -%} + {%- endif -%} + + {%- if name | lower in module_caps -%} + {{- name | upper -}} + {%- else -%} + {{- name | title -}} + {%- endif -%} +{%- endmacro -%} + +{%- if show_headings -%} + {{- formatname(basename) | e | heading }} + +.. inheritance-diagram:: {{ basename }} + :parts: 1 +{%- endif %} + +.. automodule:: {{ qualname }} + {% for option in automodule_options -%} + :{{ option }}: + {% endfor -%} \ No newline at end of file diff --git a/docs/_templates/package.rst_t b/docs/_templates/package.rst_t new file mode 100644 index 00000000..be450a60 --- /dev/null +++ b/docs/_templates/package.rst_t @@ -0,0 +1,90 @@ +{%- set is_root = pkgname == project -%} +{%- set module_footer = ["base", "exception"] -%} +{%- set module_caps = ["api", "m3u", "xautopf", "flac", "mp3", "m4a", "wma"] -%} + +{%- macro formatname(name) -%} + {%- if name.endswith(".exception") -%} + {%- set name = "exceptions"-%} + {%- else -%} + {%- set name = name.replace("syncify.", "").split(".") | last -%} + {%- endif -%} + + {%- if name | lower in module_caps -%} + {{- name | upper -}} + {%- else -%} + {{- name | title -}} + {%- endif -%} +{%- endmacro -%} + +{%- macro toctree(docnames, caption) %} +.. toctree:: + :maxdepth: {{ maxdepth }} + :caption: {{ caption }}: + + {% for docname in docnames if docname.rstrip("s") not in module_footer -%} + {{ docname }} + {% endfor -%} + + {% for docname in docnames if docname.rstrip("s") in module_footer -%} + {{ docname }} + {% endfor -%} +{%- endmacro -%} + +{%- macro automodule(modname, options) %} +.. automodule:: {{ modname }} + {% for option in automodule_options -%} + :{{ option }}: + {% endfor -%} +{%- endmacro -%} + +{%- macro autosubmodule(modname, options) %} + {%- if show_headings -%} + {{ formatname(modname) | e | heading(1 if is_root else 2) }} + +.. inheritance-diagram:: {{ modname }} + :parts: 1 + {% endif -%} + + {{ automodule(modname, automodule_options) -}} +{%- endmacro -%} + +{%- if not is_root -%} + {%- if is_namespace %} + {{- formatname(pkgname) | e | heading }} + {% else -%} + {{- formatname(pkgname) | e | heading }} + {% endif -%} + + {% if is_namespace -%} + .. py:module:: {{ pkgname }} + {%- endif -%} + + {% if modulefirst and not is_namespace -%} + {{- automodule(pkgname, automodule_options) -}} + {%- endif -%} + + {%- if subpackages -%} + {{- toctree(subpackages, "Subpackages") -}} + {%- endif -%} +{%- endif -%} + +{%- if submodules and (not separatemodules or not is_root) -%} + {%- if not is_root and separatemodules -%} + {{- toctree(submodules, "Submodules") -}} + {% else %} + {% for submodule in submodules if not submodule.split(".")[-1] in module_footer -%} + {{- autosubmodule(submodule, automodule_options) }} + {% endfor %} + {%- for submodule in submodules if submodule.split(".")[-1] in module_footer -%} + {{- autosubmodule(submodule, automodule_options) }} + {% endfor %} + {%- endif -%} + + {%- if not modulefirst and not is_namespace -%} + Module contents + --------------- + + {{- automodule(pkgname, automodule_options) -}} + {%- endif -%} + +{%- endif -%} diff --git a/docs/_templates/toc.rst_t b/docs/_templates/toc.rst_t new file mode 100644 index 00000000..291a1940 --- /dev/null +++ b/docs/_templates/toc.rst_t @@ -0,0 +1,9 @@ +{{ header | heading }} + +.. toctree:: + :maxdepth: {{ maxdepth }} + +{% for docname in docnames %} + {{ docname }} +{%- endfor %} + diff --git a/docs/conf.py b/docs/conf.py index 7e3176e9..3fff8cdb 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -3,8 +3,9 @@ # For the full list of built-in configuration values, see the documentation: # https://www.sphinx-doc.org/en/master/usage/configuration.html from datetime import datetime +from os.path import dirname, basename -from syncify import PROGRAM_NAME, PROGRAM_OWNER_NAME, __version__ +from syncify import PROGRAM_NAME, PROGRAM_OWNER_NAME, __version__, PROGRAM_URL, MODULE_ROOT, PROGRAM_OWNER_USER # -- Project information ----------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information @@ -19,11 +20,22 @@ extensions = [ - 'sphinx.ext.autodoc', # Core library for html generation from docstrings - 'sphinx.ext.autosummary', # Create neat summary tables - 'sphinx_rtd_theme' + 'sphinx.ext.autodoc', + 'sphinx_rtd_theme', + 'sphinx.ext.graphviz', + 'sphinx.ext.inheritance_diagram', + 'autodocsumm', ] -autosummary_generate = True # Turn on sphinx.ext.autosummary +autodoc_member_order = 'bysource' +autodoc_default_options = { + "autosummary": True, + "members": True, + "undoc-members": False, + "inherited-members": False, + "special-members": False, + "show-inheritance": True, + # "member-order": 'bysource', +} templates_path = ['_templates'] exclude_patterns = ["_build"] @@ -31,5 +43,29 @@ # -- Options for HTML output ------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output -html_theme = 'renku' html_static_path = ['_static'] +html_theme = 'renku' +html_theme_options = dict( + collapse_navigation=False, + sticky_navigation=True, + navigation_depth=-1, + includehidden=True, + titles_only=False, +) +html_css_files = [ + 'style.css', +] +html_context = dict( + display_github=True, + github_user=PROGRAM_OWNER_USER, + github_repo=MODULE_ROOT, + github_version="HEAD", + conf_py_path=f"/{basename(dirname(__file__))}/", +) + +# -- GraphViz configuration ---------------------------------- +graphviz_output_format = 'svg' +inheritance_graph_attrs = dict(rankdir="TB", size='""', + fontsize=10, ratio='auto', + center='true', style='solid') +inheritance_node_attrs = dict(shape='ellipse', fontsize=10, fontname="monospace") diff --git a/docs/index.rst b/docs/index.rst index efadbfce..a9efc3bf 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,13 +8,11 @@ Welcome to Syncify! .. toctree:: :maxdepth: 2 - :caption: Contents: + :caption: 📖 Reference: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + syncify.local + syncify.processors + syncify.shared + syncify.spotify + syncify.report + genindex diff --git a/pyproject.toml b/pyproject.toml index 25ea69e7..e3f90a38 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -49,6 +49,8 @@ dev = [ docs = [ "sphinx~=7.2", "renku_sphinx_theme", + "graphviz~=0.20", + "autodocsumm~=0.2", ] [project.urls] diff --git a/src/syncify/spotify/api/api.py b/src/syncify/spotify/api/api.py index 7db51639..9f2a23c9 100644 --- a/src/syncify/spotify/api/api.py +++ b/src/syncify/spotify/api/api.py @@ -8,7 +8,6 @@ from syncify.spotify.api.item import SpotifyAPIItems from syncify.spotify.api.misc import SpotifyAPIMisc from syncify.spotify.api.playlist import SpotifyAPIPlaylists -from syncify.spotify.processors.wrangle import SpotifyDataWrangler # user authenticated access with scopes SPOTIFY_API_AUTH_ARGS = { @@ -54,10 +53,9 @@ } -class SpotifyAPI(SpotifyAPIMisc, SpotifyAPIItems, SpotifyAPIPlaylists, SpotifyDataWrangler): +class SpotifyAPI(SpotifyAPIMisc, SpotifyAPIItems, SpotifyAPIPlaylists): """ Collection of endpoints for the Spotify API. - See :py:class:`RequestHandler` for more info on optional params to pass as ``**kwargs``. :param client_id: The client ID to use when authorising requests. :param client_secret: The client secret to use when authorising requests. diff --git a/src/syncify/spotify/api/base.py b/src/syncify/spotify/api/base.py index 704267e0..7a34a9d3 100644 --- a/src/syncify/spotify/api/base.py +++ b/src/syncify/spotify/api/base.py @@ -3,9 +3,10 @@ from urllib.parse import parse_qs, urlparse, urlencode, quote, urlunparse from syncify.shared.remote.api import RemoteAPI +from syncify.spotify.processors.wrangle import SpotifyDataWrangler -class SpotifyAPIBase(RemoteAPI, metaclass=ABCMeta): +class SpotifyAPIBase(RemoteAPI, SpotifyDataWrangler, metaclass=ABCMeta): items_key = "items"