From 2cf9f75e380e10f7623b08621bc5b2f671afa9f7 Mon Sep 17 00:00:00 2001 From: Johannes Tiefenbacher Date: Sat, 12 Oct 2024 11:46:55 +0200 Subject: [PATCH 1/3] docs: Try out the PyData Sphinx theme --- docs/source/_static/p3dc.css | 11 +++++++++++ docs/source/conf.py | 38 +++++++++++++++++++++++------------- setup.py | 2 +- 3 files changed, 36 insertions(+), 15 deletions(-) create mode 100644 docs/source/_static/p3dc.css diff --git a/docs/source/_static/p3dc.css b/docs/source/_static/p3dc.css new file mode 100644 index 0000000..17b6290 --- /dev/null +++ b/docs/source/_static/p3dc.css @@ -0,0 +1,11 @@ +html { + --pst-font-size-base: 14px; + --pst-header-height: 5rem; +} + +@media (prefers-reduced-motion) { + .bd-sidebar-primary, .bd-sidebar-secondary { + transition-duration: 0s; + } +} + diff --git a/docs/source/conf.py b/docs/source/conf.py index cf7aede..b2b5e2a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -50,24 +50,34 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. # -html_theme = 'sphinx_rtd_theme' - -# Add any paths that contain custom static files (such as style sheets) here, -# relative to this directory. They are copied after the builtin static files, -# so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] - -html_theme_options = { - 'collapse_navigation': False, - 'navigation_depth': 8, - 'sticky_navigation': True, - 'prev_next_buttons_location': 'bottom' -} +html_theme = "pydata_sphinx_theme" html_last_updated_fmt = "%b %d, %Y" - html_logo = '_static/discogs-vinyl-record-mark-50x50.png' +html_context = { + "github_user": "joalla", + "github_repo": "discogs_client", + "github_version": "master", + "doc_path": "docs/source/", +} +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/joalla/discogs_client", + "icon": "fa-brands fa-github", + }, + ], + "use_edit_page_button": True, + "header_links_before_dropdown": 3, + "show_toc_level": 5, + "back_to_top_button": False, +} +html_title = "" +html_static_path = ["_static"] +html_css_files = ["p3dc.css"] +# MyST extenstion configuration myst_heading_anchors = 7 myst_enable_extensions = [ "substitution" diff --git a/setup.py b/setup.py index 2dcba81..c4da539 100755 --- a/setup.py +++ b/setup.py @@ -32,7 +32,7 @@ extras_require={ "docs": [ "sphinx", - "sphinx-rtd-theme", + "pydata-sphinx-theme", "myst-parser", ], } From 3c9737fc05bbd8c8977dda226c9a4ea64d97f57d Mon Sep 17 00:00:00 2001 From: Johannes Tiefenbacher Date: Sun, 13 Oct 2024 15:51:18 +0200 Subject: [PATCH 2/3] docs: Enable floating back to top button --- docs/source/conf.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b2b5e2a..ef9373b 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -71,7 +71,7 @@ "use_edit_page_button": True, "header_links_before_dropdown": 3, "show_toc_level": 5, - "back_to_top_button": False, + "back_to_top_button": True, } html_title = "" html_static_path = ["_static"] From 44dce6d286557389b8ddce2d6531dbab1287cf8a Mon Sep 17 00:00:00 2001 From: Johannes Tiefenbacher Date: Sun, 13 Oct 2024 15:54:17 +0200 Subject: [PATCH 3/3] docs: Restructure Python package docs - This enables "Section Navigation" - Each module has it's own .rst file with a "main section headline", - and is bound together by a "subindex" defined by index_discogs_client.rst --- docs/source/discogs_client.client.rst | 4 ++++ docs/source/discogs_client.exceptions.rst | 5 +++++ docs/source/discogs_client.fetchers.rst | 5 +++++ docs/source/discogs_client.models.rst | 5 +++++ docs/source/discogs_client.rst | 27 ----------------------- docs/source/discogs_client.utils.rst | 5 +++++ docs/source/index.rst | 2 +- docs/source/index_discogs_client.rst | 13 +++++++++++ 8 files changed, 38 insertions(+), 28 deletions(-) create mode 100644 docs/source/discogs_client.client.rst create mode 100644 docs/source/discogs_client.exceptions.rst create mode 100644 docs/source/discogs_client.fetchers.rst create mode 100644 docs/source/discogs_client.models.rst delete mode 100644 docs/source/discogs_client.rst create mode 100644 docs/source/discogs_client.utils.rst create mode 100644 docs/source/index_discogs_client.rst diff --git a/docs/source/discogs_client.client.rst b/docs/source/discogs_client.client.rst new file mode 100644 index 0000000..a3ddeb4 --- /dev/null +++ b/docs/source/discogs_client.client.rst @@ -0,0 +1,4 @@ +discogs\_client.client module +============================= + +.. automodule:: discogs_client.client diff --git a/docs/source/discogs_client.exceptions.rst b/docs/source/discogs_client.exceptions.rst new file mode 100644 index 0000000..c1856b9 --- /dev/null +++ b/docs/source/discogs_client.exceptions.rst @@ -0,0 +1,5 @@ +discogs\_client.exceptions module +================================= + +.. automodule:: discogs_client.exceptions + diff --git a/docs/source/discogs_client.fetchers.rst b/docs/source/discogs_client.fetchers.rst new file mode 100644 index 0000000..e4f7aa3 --- /dev/null +++ b/docs/source/discogs_client.fetchers.rst @@ -0,0 +1,5 @@ +discogs\_client.fetchers module +=============================== + +.. automodule:: discogs_client.fetchers + diff --git a/docs/source/discogs_client.models.rst b/docs/source/discogs_client.models.rst new file mode 100644 index 0000000..723c276 --- /dev/null +++ b/docs/source/discogs_client.models.rst @@ -0,0 +1,5 @@ +discogs\_client.models module +============================= + +.. automodule:: discogs_client.models + diff --git a/docs/source/discogs_client.rst b/docs/source/discogs_client.rst deleted file mode 100644 index 5b02eed..0000000 --- a/docs/source/discogs_client.rst +++ /dev/null @@ -1,27 +0,0 @@ -discogs\_client package -======================= - -discogs\_client.client module ------------------------------ - -.. automodule:: discogs_client.client - -discogs\_client.exceptions module ---------------------------------- - -.. automodule:: discogs_client.exceptions - -discogs\_client.fetchers module -------------------------------- - -.. automodule:: discogs_client.fetchers - -discogs\_client.models module ------------------------------ - -.. automodule:: discogs_client.models - -discogs\_client.utils module ----------------------------- - -.. automodule:: discogs_client.utils diff --git a/docs/source/discogs_client.utils.rst b/docs/source/discogs_client.utils.rst new file mode 100644 index 0000000..61ea23d --- /dev/null +++ b/docs/source/discogs_client.utils.rst @@ -0,0 +1,5 @@ +discogs\_client.utils module +============================ + +.. automodule:: discogs_client.utils + diff --git a/docs/source/index.rst b/docs/source/index.rst index bcbf49b..9c4e028 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -19,7 +19,7 @@ python3-discogs-client documentation optional_configuration.md contributing.md writing_docs.md - discogs_client + index_discogs_client Indices and tables diff --git a/docs/source/index_discogs_client.rst b/docs/source/index_discogs_client.rst new file mode 100644 index 0000000..e91144e --- /dev/null +++ b/docs/source/index_discogs_client.rst @@ -0,0 +1,13 @@ +discogs_client package +====================== + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + + discogs_client.client + discogs_client.exceptions + discogs_client.fetchers + discogs_client.models + discogs_client.utils +