reformat reference documentation layout

.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

docs/_static/style.css

@@ -0,0 +1,3 @@
+.wy-nav-content {
+    max-width: 1200px !important;
+}

docs/_templates/autosummary/base.rst

@@ -0,0 +1,5 @@
+{{ fullname | escape | underline}}
+
+.. currentmodule:: {{ module }}
+
+.. auto{{ objtype }}:: {{ objname }}

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 -%}

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 %}

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 -%}

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 -%}

docs/_templates/toc.rst_t

@@ -0,0 +1,9 @@
+{{ header | heading }}
+
+.. toctree::
+   :maxdepth: {{ maxdepth }}
+
+{% for docname in docnames %}
+   {{ docname }}
+{%- endfor %}
+

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,17 +20,52 @@
 
 
 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"]
 
 # -- 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")

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

pyproject.toml

@@ -49,6 +49,8 @@ dev = [
 docs = [
     "sphinx~=7.2",
     "renku_sphinx_theme",
+    "graphviz~=0.20",
+    "autodocsumm~=0.2",
 ]
 
 [project.urls]