From 5b2da50a3ccf3864233927afef36470364229cd5 Mon Sep 17 00:00:00 2001 From: zed tan Date: Mon, 22 Aug 2022 10:18:56 +0200 Subject: [PATCH 1/5] Update build params for better navigation and to use sphinx_rtd_theme Updated .readthedocs.yaml to: - Use more explicit build parameters - explicitly use 'dirhtml' as output for pretty urls Updated conf.py to: - include 'sphinx_rtd_theme' and 'readthedocs-sphinx-search' extensions, which were already included in docs/requirements.txt - set theme to 'sphinx_rtd_theme' - replace html config with sphinx_rtd_theme config What this means: - automatically populate sidebar instead of explicitly populating it - sidebar should now contain all docs. now, you can navigate the docs through that instead of having to navigate almost exclusively through the 'next' and 'previous' buttons --- .readthedocs.yaml | 7 ++- docs/conf.py | 109 +++++++++++----------------------------------- 2 files changed, 32 insertions(+), 84 deletions(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index c1d97eb3..d87cad5a 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -3,9 +3,14 @@ version: 2 # Build from the docs/ directory with Sphinx sphinx: configuration: docs/conf.py + builder: "dirhtml" # Explicitly set the version of Python and its requirements +build: + os: "ubuntu-20.04" + tools: + python: "3.7" + python: - version: 3.7 install: - requirements: docs/requirements.txt diff --git a/docs/conf.py b/docs/conf.py index 58a79d60..c523ed08 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -30,7 +30,12 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - 'sphinx.ext.autodoc', 'sphinx.ext.coverage', 'sphinx.ext.extlinks'] + 'sphinx.ext.autodoc', + 'sphinx.ext.coverage', + 'sphinx.ext.extlinks', + 'sphinx_rtd_theme', + 'readthedocs-sphinx-search', + ] # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] @@ -106,90 +111,28 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' - -# Theme options are theme-specific and customize the look and feel of a theme -# further. For a list of options available for each theme, see the -# documentation. -#html_theme_options = {} - -# Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] - -# The name for this set of Sphinx documents. If None, it defaults to -# " v documentation". -#html_title = None - -# A shorter title for the navigation bar. Default is the same as html_title. -#html_short_title = None - -# The name of an image file (relative to this directory) to place at the top -# of the sidebar. -#html_logo = None - -# The name of an image file (within the static path) to use as favicon of the -# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 -# pixels large. -#html_favicon = None - -# 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'] - -# Add any extra paths that contain custom files (such as robots.txt or -# .htaccess) here, relative to this directory. These files are copied -# directly to the root of the documentation. -#html_extra_path = [] - -# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, -# using the given strftime format. -#html_last_updated_fmt = '%b %d, %Y' - -# If true, SmartyPants will be used to convert quotes and dashes to -# typographically correct entities. -#html_use_smartypants = True - -# Custom sidebar templates, maps document names to template names. -html_sidebars = { - 'index': ['sidebarintro.html', 'sourcelink.html', 'searchbox.html'], - '**': ['localtoc.html', 'relations.html', - 'sourcelink.html', 'searchbox.html'] +html_theme = 'sphind_rtd_theme' + +# -- sphinx-rtd-theme options ----------- + +html_theme_options = { + # 'analytics_id': 'G-XXXXXXXXXX', # Provided by Google in your dashboard + # 'analytics_anonymize_ip': False, + 'logo_only': False, + 'display_version': True, + # 'canonical_url': 'https://opentaxii.readthedocs.io/', # important when we host on multiple urls + 'prev_next_buttons_location': 'bottom', + 'style_external_links': True, + 'vcs_pageview_mode': '', + 'style_nav_header_background': 'white', + # Toc options + 'collapse_navigation': True, + 'sticky_navigation': True, + 'navigation_depth': 4, + 'includehidden': True, + 'titles_only': True, } -# Additional templates that should be rendered to pages, maps page names to -# template names. -#html_additional_pages = {} - -# If false, no module index is generated. -html_domain_indices = False - -# If false, no index is generated. -#html_use_index = True - -# If true, the index is split into individual pages for each letter. -#html_split_index = False - -# If true, links to the reST sources are added to the pages. -html_show_sourcelink = False - -# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. -html_show_sphinx = False - -# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. -#html_show_copyright = True - -# If true, an OpenSearch description file will be output, and all pages will -# contain a tag referring to it. The value of this option must be the -# base URL from which the finished HTML is served. -#html_use_opensearch = '' - -# This is the file name suffix for HTML files (e.g. ".xhtml"). -#html_file_suffix = None - -# Output file base name for HTML help builder. -htmlhelp_basename = 'opentaxiidoc' - # -- Options for LaTeX output --------------------------------------------- From c2aa8bbc5bb41b0844227034ce8b33e93861a2f4 Mon Sep 17 00:00:00 2001 From: zed tan Date: Mon, 22 Aug 2022 10:28:10 +0200 Subject: [PATCH 2/5] bump readthedocs python version to 3.9 to match version repo is tested with --- .readthedocs.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.readthedocs.yaml b/.readthedocs.yaml index d87cad5a..e23d4f20 100644 --- a/.readthedocs.yaml +++ b/.readthedocs.yaml @@ -9,7 +9,7 @@ sphinx: build: os: "ubuntu-20.04" tools: - python: "3.7" + python: "3.9" python: install: From a71196984907e4955bb436af20c93af71aa3497d Mon Sep 17 00:00:00 2001 From: zed tan Date: Mon, 22 Aug 2022 12:22:39 +0200 Subject: [PATCH 3/5] fix bad extension reference; fix theme name typo; fixed bad theme nav header background --- docs/conf.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/conf.py b/docs/conf.py index c523ed08..e79fab28 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -34,7 +34,7 @@ 'sphinx.ext.coverage', 'sphinx.ext.extlinks', 'sphinx_rtd_theme', - 'readthedocs-sphinx-search', + 'sphinx_search.extension', ] # Add any paths that contain templates here, relative to this directory. @@ -111,7 +111,7 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphind_rtd_theme' +html_theme = 'sphinx_rtd_theme' # -- sphinx-rtd-theme options ----------- @@ -124,7 +124,7 @@ 'prev_next_buttons_location': 'bottom', 'style_external_links': True, 'vcs_pageview_mode': '', - 'style_nav_header_background': 'white', + #'style_nav_header_background': 'white', # Toc options 'collapse_navigation': True, 'sticky_navigation': True, From b7d31863cb3eb9b48fcb7f5ea6df456789a55faf Mon Sep 17 00:00:00 2001 From: zed tan Date: Fri, 26 Aug 2022 10:20:24 +0200 Subject: [PATCH 4/5] show page subheaders in left nav --- docs/conf.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/conf.py b/docs/conf.py index e79fab28..db154e51 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -15,6 +15,7 @@ import datetime import sys import os +import sphinx_rtd_theme # If extensions (or modules to document with autodoc) are in another directory, # add these directories to sys.path here. If the directory is relative to the @@ -130,7 +131,7 @@ 'sticky_navigation': True, 'navigation_depth': 4, 'includehidden': True, - 'titles_only': True, + 'titles_only': False, } From 637fdec4f8789dc7aa718a7d8f34198c7c172f6a Mon Sep 17 00:00:00 2001 From: Erwin Junge Date: Fri, 26 Aug 2022 14:04:11 +0200 Subject: [PATCH 5/5] Version bump --- CHANGES.rst | 4 ++++ opentaxii/_version.py | 2 +- 2 files changed, 5 insertions(+), 1 deletion(-) diff --git a/CHANGES.rst b/CHANGES.rst index 58d7fcbe..8f555857 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -1,6 +1,10 @@ Changelog ========= +0.9.2 (2022-08-26) +------------------ +* Improve readability and navigation of docs (`#238 `_ thanks `@zed-eiq `_ for the improvement). + 0.9.1 (2022-07-11) ------------------ * Implement `raise_unauthorized` for taxii2, this was missing and lead to 500 errors. diff --git a/opentaxii/_version.py b/opentaxii/_version.py index ce8ed276..d90743b8 100644 --- a/opentaxii/_version.py +++ b/opentaxii/_version.py @@ -3,4 +3,4 @@ This module defines the package version for use in __init__.py and setup.py. """ -__version__ = '0.9.1' +__version__ = '0.9.2'