From a8c6b9cc30fda1a9ab3a3bb46df39cdbe118e392 Mon Sep 17 00:00:00 2001 From: stanley Date: Fri, 18 Nov 2022 06:58:01 +0000 Subject: [PATCH 01/28] Update version info for release - 3.8.0 --- version.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/version.txt b/version.txt index 2090923e..cc1923a4 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.8dev +3.8 From be2c68e6133d356726abdc0a3f4365c350e04fab Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:19:31 -0500 Subject: [PATCH 02/28] move _static/*.css -> _static/css/ --- docs/source/_static/{ => css}/theme_overrides.css | 0 docs/source/conf.py | 2 +- 2 files changed, 1 insertion(+), 1 deletion(-) rename docs/source/_static/{ => css}/theme_overrides.css (100%) diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/css/theme_overrides.css similarity index 100% rename from docs/source/_static/theme_overrides.css rename to docs/source/_static/css/theme_overrides.css diff --git a/docs/source/conf.py b/docs/source/conf.py index b774253f..08f9a490 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -292,7 +292,7 @@ def previous_version(ver): ], 'current_version': version, 'css_files': [ - '_static/theme_overrides.css', + '_static/css/theme_overrides.css', ], } From ff0ae0316cf00144359303f4f17efc0a2126b51c Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:23:56 -0500 Subject: [PATCH 03/28] switch from old forked in-repo theme to upstream 1.0.0 --- docs/source/conf.py | 5 +++-- requirements.txt | 1 + 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 08f9a490..b401dfb2 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -16,6 +16,8 @@ import os import glob +import sphinx_rtd_theme + BASE_DIR = os.path.dirname(os.path.abspath(__file__)) ROOT_DIR = os.path.abspath(os.path.join(BASE_DIR, '../../st2')) @@ -30,7 +32,7 @@ # 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 # documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('./_themes')) +# sys.path.insert(0, os.path.abspath('./path/to/extension')) from st2common import __version__ @@ -203,7 +205,6 @@ def previous_version(ver): # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] -html_theme_path = ["_themes", ] # The name for this set of Sphinx documents. If None, it defaults to # " v documentation". diff --git a/requirements.txt b/requirements.txt index 99b729ac..e69ae5c1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ docutils==0.16.0 sphinx>=2.4.4,<3.0 sphinx-autobuild sphinx-sitemap==2.1.0 +sphinx-rtd-theme==1.0.0 jinja2<3.1 From 717a32b6a90f81b5d90d7ce1809afa036a65d7f4 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:38:36 -0500 Subject: [PATCH 04/28] switch to standard sphinx var for html_base_url rtd-sphinx-theme says that the "canonical_url" setting is deprecated in favor of the standard sphinx "html_base_url". see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html#confval-canonical_url see: https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_baseurl --- docs/source/conf.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index b401dfb2..75e6ff25 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -198,10 +198,11 @@ def previous_version(ver): # 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 = { - 'base_url': info.theme_base_url, - 'canonical_url': info.theme_base_url -} +html_theme_options = {} + +if "READTHEDOCS" not in os.environ: + # set the canonical url to our custom domain unless testing on RTD + html_base_url = info.theme_base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From f933b1c2e0d053505b179d78ee3317543cf2cd9a Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 22:42:25 -0500 Subject: [PATCH 05/28] port logo and favicon to new theme these were embedded in the old forked theme. --- .../source/_static/css/rtd_theme_overrides.css | 7 +++++++ docs/source/_static/images/favicon.ico | Bin 0 -> 1150 bytes docs/source/_static/images/logo.svg | 17 +++++++++++++++++ docs/source/conf.py | 17 +++++++++++------ 4 files changed, 35 insertions(+), 6 deletions(-) create mode 100644 docs/source/_static/css/rtd_theme_overrides.css create mode 100644 docs/source/_static/images/favicon.ico create mode 100644 docs/source/_static/images/logo.svg diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css new file mode 100644 index 00000000..cce4f3bc --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -0,0 +1,7 @@ +.wy-side-nav-search .wy-dropdown>a img.logo, .wy-side-nav-search>a img.logo { + display: block; + width: 160px; + + /* svg defaults to fill: #000 */ + filter: invert(100%); /* effectively - fill: #fff */ +} diff --git a/docs/source/_static/images/favicon.ico b/docs/source/_static/images/favicon.ico new file mode 100644 index 0000000000000000000000000000000000000000..64880c4f5c938cadae229c70f9c29ad1cf47cd75 GIT binary patch literal 1150 zcmb`FF;2rk5Je{<5<)bFf;x1RIZ8?*nv|3|f)gm{as(fNBRDyMkH8Upg2=qT@mQm1 z0V7ECyz8BLIAkINQGWHpH@f72@e^{n@?$lcTtvk + + + + + + + + + + + + + + + + diff --git a/docs/source/conf.py b/docs/source/conf.py index 75e6ff25..0028b5ec 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -198,7 +198,15 @@ def previous_version(ver): # 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 = {} +html_theme_options = { + # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html + "logo_only": True, +} + +html_css_files = [ + "css/theme_overrides.css", + "css/rtd_theme_overrides.css", +] if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD @@ -216,12 +224,12 @@ def previous_version(ver): # The name of an image file (relative to this directory) to place at the top # of the sidebar. -# html_logo = None +html_logo = "_static/images/logo.svg" # 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 = "favicon.ico" +html_favicon = "_static/images/favicon.ico" # 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, @@ -293,9 +301,6 @@ def previous_version(ver): (version_minus_2, '%s%s' % (info.base_url, version_minus_2)), ], 'current_version': version, - 'css_files': [ - '_static/css/theme_overrides.css', - ], } From 147ac3056271f6e5402e65788ea400ab4e008b55 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:00:14 -0500 Subject: [PATCH 06/28] port external link handling to new theme --- docs/source/_static/js/rtd_theme_overrides.js | 4 ++++ docs/source/conf.py | 4 ++++ 2 files changed, 8 insertions(+) create mode 100644 docs/source/_static/js/rtd_theme_overrides.js diff --git a/docs/source/_static/js/rtd_theme_overrides.js b/docs/source/_static/js/rtd_theme_overrides.js new file mode 100644 index 00000000..ad9df4b3 --- /dev/null +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -0,0 +1,4 @@ +$( document ).ready(function() { + // Open external links in another tab/window + $(".external").attr("target","_blank"); +}); diff --git a/docs/source/conf.py b/docs/source/conf.py index 0028b5ec..ae3259cf 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -201,12 +201,16 @@ def previous_version(ver): html_theme_options = { # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html "logo_only": True, + "style_external_links": True, } html_css_files = [ "css/theme_overrides.css", "css/rtd_theme_overrides.css", ] +html_js_files = [ + "js/rtd_theme_overrides.js", +] if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD From d583a99509c0c46bb263ac01f043618127dc1265 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:01:55 -0500 Subject: [PATCH 07/28] port version-in-breadcrumb to new theme --- docs/source/_static/css/rtd_theme_overrides.css | 4 ++++ docs/source/_static/js/rtd_theme_overrides.js | 5 +++++ docs/source/conf.py | 2 ++ 3 files changed, 11 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index cce4f3bc..2c72e4ea 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -5,3 +5,7 @@ /* svg defaults to fill: #000 */ filter: invert(100%); /* effectively - fill: #fff */ } + +.wy-breadcrumbs li a.icon-home:before { + content: "" /* drop the icon. js will add content */ +} diff --git a/docs/source/_static/js/rtd_theme_overrides.js b/docs/source/_static/js/rtd_theme_overrides.js index ad9df4b3..9bd64424 100644 --- a/docs/source/_static/js/rtd_theme_overrides.js +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -1,4 +1,9 @@ $( document ).ready(function() { // Open external links in another tab/window $(".external").attr("target","_blank"); + // List the docs version in breadcrumbs + $(".wy-breadcrumbs li a.icon-home").text( + // DOCUMENTATION_OPTIONS is a sphinx feature + "Docs v" + DOCUMENTATION_OPTIONS.VERSION + ) }); diff --git a/docs/source/conf.py b/docs/source/conf.py index ae3259cf..860c0287 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -201,6 +201,8 @@ def previous_version(ver): html_theme_options = { # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html "logo_only": True, + # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead + "display_version": False, "style_external_links": True, } From 81a9fa444e3d6dbfdbdaa639ed3d20fe967d18b8 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:04:44 -0500 Subject: [PATCH 08/28] port colors (with tweaks) to new theme --- .../_static/css/rtd_theme_overrides.css | 38 +++++++++++++++++++ docs/source/conf.py | 1 + 2 files changed, 39 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 2c72e4ea..2df786e5 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,41 @@ +/** + * st2 orange: #fb8225 + * 5% lighter: #fb903e + * 20% darker: #b75103 + * + * st2 gray: #4d585a + * 5% lighter: #596568 + **/ +.wy-menu-vertical li.current a:hover { + color: #b75103; +} +.wy-menu-vertical li a:hover { + color: #fb8225; +} +.wy-menu-vertical li.on a:hover, .wy-menu-vertical li.current > a:hover { + color: #b75103; +} +.wy-menu-vertical li.toctree-l2.current>a { + background-color: #fb8225; + color: #FFF; +} +.wy-side-nav-search { + background-color: #fb8225; +} +.wy-menu-vertical header,.wy-menu-vertical p.caption { + color: #fb903e; +} +.wy-side-nav-search input[type=text] { + border-color: #fcd531; +} + +.wy-menu-vertical a:hover { + background-color: #596568; +} +.wy-nav-top, .wy-nav-side { + background: #4d585a; +} + .wy-side-nav-search .wy-dropdown>a img.logo, .wy-side-nav-search>a img.logo { display: block; width: 160px; diff --git a/docs/source/conf.py b/docs/source/conf.py index 860c0287..c8acd47d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -200,6 +200,7 @@ def previous_version(ver): # documentation. html_theme_options = { # see: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html + # "style_nav_header_background": "#fb8225", # covered by rtd_theme_overrides.css "logo_only": True, # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead "display_version": False, From 01225620316c7202db487f72082f9d5b5fb01ea2 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:11:15 -0500 Subject: [PATCH 09/28] port fonts to new theme only missing the link that was in the old theme layout: https://github.com/StackStorm/st2docs/blob/828b2a2a7b3e24630aee816303cb0cad50115bf3/docs/source/_themes/sphinx_rtd_theme/layout.html#L35 --- .../_static/css/rtd_theme_overrides.css | 30 ++++++++++++++++++- .../css/rtd_theme_overrides.unused.css | 25 ++++++++++++++++ 2 files changed, 54 insertions(+), 1 deletion(-) create mode 100644 docs/source/_static/css/rtd_theme_overrides.unused.css diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 2df786e5..04855219 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,31 @@ +/* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ +.btn { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +input[type="button"], input[type="reset"], input[type="submit"] { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +input[type="color"], input[type="date"], input[type="datetime-local"], input[type="datetime"], input[type="email"], input[type="month"], input[type="number"], input[type="password"], input[type="search"], input[type="tel"], input[type="text"], input[type="time"], input[type="url"], input[type="week"] { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +textarea { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +body { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-versions { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} + +/* $custom-font-family: Roboto Slab,ff-tisa-web-pro,Georgia,Arial,sans-serif */ +.rst-content .toctree-wrapper>p.caption, h1, h2, h3, h4, h5, h6, legend { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .sidebar .sidebar-title { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} + /** * st2 orange: #fb8225 * 5% lighter: #fb903e @@ -39,7 +67,7 @@ .wy-side-nav-search .wy-dropdown>a img.logo, .wy-side-nav-search>a img.logo { display: block; width: 160px; - + /* svg defaults to fill: #000 */ filter: invert(100%); /* effectively - fill: #fff */ } diff --git a/docs/source/_static/css/rtd_theme_overrides.unused.css b/docs/source/_static/css/rtd_theme_overrides.unused.css new file mode 100644 index 00000000..8c26ea6e --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.unused.css @@ -0,0 +1,25 @@ +/* $code-font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace; */ +.rst-content code, .rst-content tt, code { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content footer span.commit tt, footer span.commit .rst-content tt, footer span.commit code { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content pre.literal-block { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .linenodiv pre { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content .linenodiv pre, .rst-content div[class^=highlight] pre, .rst-content pre.literal-block { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content code, .rst-content tt { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +.rst-content kbd,.rst-content pre,.rst-content samp { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} +html.writer-html4 .rst-content dl:not(.docutils) .descclassname,html.writer-html4 .rst-content dl:not(.docutils) .descname,html.writer-html4 .rst-content dl:not(.docutils) .sig-name,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descclassname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .descname,html.writer-html5 .rst-content dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple) .sig-name { + font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; +} From cb03969a67ee4a5840708451e2bf0c41d65e8cf4 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:13:13 -0500 Subject: [PATCH 10/28] remove max-width on new theme --- docs/source/_static/css/rtd_theme_overrides.css | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 04855219..0c6ec0a6 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -1,3 +1,8 @@ +/* layout changes */ +.wy-nav-content { + max-width: none; /* was 800px */ +} + /* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ .btn { font-family: "Open Sans", "Helvetica Neue", Arial, sans-serif; From 3f9f5362054f8ac986a5a29a8fccfc88801704b1 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:23:51 -0500 Subject: [PATCH 11/28] configure the vcs link bits of the theme --- docs/source/conf.py | 10 ++++++---- docs/source/info.py | 6 +++--- 2 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index c8acd47d..e31a123a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -205,6 +205,7 @@ def previous_version(ver): # display_version puts rtd slug/version at top of sidebar, but we use breadcrumbs instead "display_version": False, "style_external_links": True, + "vcs_pageview_mode": "blob", # blob, edit, raw } html_css_files = [ @@ -295,11 +296,12 @@ def previous_version(ver): # Variables to be used by templates html_context = { - 'github_user': info.github_user, - 'github_repo': info.github_repo, - 'github_version': info.github_version, + # The github settings configure the "Edit on GitHub" link + "display_github": True, + "github_user": info.github_user, + "github_repo": info.github_repo, + "github_version": info.github_version, 'conf_py_path': '/docs/source/', - 'display_github': True, 'source_suffix': source_suffix, 'versions': [ ('latest', '%slatest' % info.base_url), diff --git a/docs/source/info.py b/docs/source/info.py index 28f47aac..fc49663d 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -30,8 +30,8 @@ 'Miscellaneous'), ] -github_user = 'StackStorm' -github_repo = 'st2docs' -github_version = 'master' +github_user = "StackStorm" +github_repo = "st2docs" +github_version = "master" theme_base_url = u'https://docs.stackstorm.com/' From ef8182ac7f15922b006ec456525afdffce92c7bd Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:25:46 -0500 Subject: [PATCH 12/28] cleanup author info --- docs/source/info.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/source/info.py b/docs/source/info.py index fc49663d..dec802a0 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -9,9 +9,9 @@ master_doc = 'index' -project = u'StackStorm' -copyright = u'2014 - %s, StackStorm' % (datetime.now().strftime("%Y")) -author = u'Extreme Networks, Inc' +project = "StackStorm" +copyright = "2014 - %s, StackStorm" % (datetime.now().strftime("%Y")) +author = "The StackStorm Authors" base_url = u'https://docs.stackstorm.com/' htmlhelp_basename = 'StackStormDoc' From b7d11c42ae192de445842266be23a45f109d2ed3 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 23 Jul 2022 23:26:50 -0500 Subject: [PATCH 13/28] drop duplicate config for base_url --- docs/source/conf.py | 2 +- docs/source/info.py | 4 +--- 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index e31a123a..680ee111 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -218,7 +218,7 @@ def previous_version(ver): if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD - html_base_url = info.theme_base_url + html_base_url = info.base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/docs/source/info.py b/docs/source/info.py index dec802a0..f487100b 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -13,7 +13,7 @@ copyright = "2014 - %s, StackStorm" % (datetime.now().strftime("%Y")) author = "The StackStorm Authors" -base_url = u'https://docs.stackstorm.com/' +base_url = "https://docs.stackstorm.com/" htmlhelp_basename = 'StackStormDoc' man_pages = [ @@ -33,5 +33,3 @@ github_user = "StackStorm" github_repo = "st2docs" github_version = "master" - -theme_base_url = u'https://docs.stackstorm.com/' From b307f045c4d2533743961164b8a6ed11a61733b9 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 24 Jul 2022 00:53:11 -0500 Subject: [PATCH 14/28] add versions bit --- docs/source/conf.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 680ee111..6f884e13 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -303,14 +303,17 @@ def previous_version(ver): "github_version": info.github_version, 'conf_py_path': '/docs/source/', 'source_suffix': source_suffix, - 'versions': [ +} + +if "READTHEDOCS" not in os.environ: + # READTHEDOCS handles versions for us. TODO: is this needed locally with the new theme? + html_context['versions'] = [ ('latest', '%slatest' % info.base_url), (version, '%s%s' % (info.base_url, version)), (version_minus_1, '%s%s' % (info.base_url, version_minus_1)), (version_minus_2, '%s%s' % (info.base_url, version_minus_2)), - ], - 'current_version': version, -} + ] + html_context['current_version'] = version # -- Options for LaTeX output --------------------------------------------- From c9725500f7c972e55f5ab3a17c92281d1cb5a93f Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sat, 30 Jul 2022 16:43:09 -0500 Subject: [PATCH 15/28] correct html_baseurl var name --- 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 6f884e13..bad9e78d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -218,7 +218,7 @@ def previous_version(ver): if "READTHEDOCS" not in os.environ: # set the canonical url to our custom domain unless testing on RTD - html_base_url = info.base_url + html_baseurl = info.base_url # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 0a2ccde123c93b8b51269d4e94c8260d403a22ce Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 01:18:19 -0500 Subject: [PATCH 16/28] add font css --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index bad9e78d..62f24c2c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -208,9 +208,12 @@ def previous_version(ver): "vcs_pageview_mode": "blob", # blob, edit, raw } +# These paths are either relative to html_static_path +# or fully qualified paths (eg. https://...) html_css_files = [ "css/theme_overrides.css", "css/rtd_theme_overrides.css", + "https://fonts.googleapis.com/css?family=Open+Sans:400,300,300italic,400italic,600,600italic,700,700italic|Inconsolata:400,700", ] html_js_files = [ "js/rtd_theme_overrides.js", From 4fa8240c6c0d694d3777ed0bc774c5253958f78a Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 11:54:46 -0500 Subject: [PATCH 17/28] add versions menu --- docs/source/_templates/version_menu.html | 38 ++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs/source/_templates/version_menu.html diff --git a/docs/source/_templates/version_menu.html b/docs/source/_templates/version_menu.html new file mode 100644 index 00000000..33ee6414 --- /dev/null +++ b/docs/source/_templates/version_menu.html @@ -0,0 +1,38 @@ +{%- extends "!layout.html" %} + +{#- + +This template exists as a way to implement a version menu in local builds +without changing what normally renders in builds on Read the +Docs. +Based on: +https://github.com/readthedocs/sphinx_rtd_theme/blob/master/docs/_templates/layout.html +https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/versions.html + +#} + +{%- block footer %} + {%- if not READTHEDOCS %} +
+ + Read the Docs + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+
+
{{ _('Downloads') }}
+ {% for type, url in downloads %} +
{{ type }}
+ {% endfor %} +
+
+
+ {%- endif %} +{%- endblock %} From 5d1629653e3d4664a3385aab4e3c77f482daff1b Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 22:08:33 -0500 Subject: [PATCH 18/28] add versions.js for backwards compat w/ previous docs versions --- docs/source/_static/js/versions.js_t | 40 ++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 docs/source/_static/js/versions.js_t diff --git a/docs/source/_static/js/versions.js_t b/docs/source/_static/js/versions.js_t new file mode 100644 index 00000000..64b24a08 --- /dev/null +++ b/docs/source/_static/js/versions.js_t @@ -0,0 +1,40 @@ +(function () { + function renderVersionBadge(versions, currentVersion) { + var versionsContainer = $('
Versions
'); + $.each(versions, function (slug, url) { + versionsContainer.append('
' + slug + '
'); + }); + + var otherVersions = $('
').append(versionsContainer); + + var container = $('
'); + container.append('v: ' + currentVersion + ' '); + container.append(otherVersions); + + $('#versions').replaceWith(container); + } + + function showVersionWarning() { + $('#version-warning').show(); + } + + $(document).ready(function () { + var latestVersion = "{{ current_version }}"; + + var versions = { + {%- for slug, url in versions %} + "{{ slug }}": "{{ url }}", + {%- endfor %} + }; + + var currentVersion = latestVersion; + + var match = window.location.pathname.match('^/(\\d+\\.\\d+)'); + if (match) { + currentVersion = match[1]; + showVersionWarning(); + } + + renderVersionBadge(versions, currentVersion); + }); +})() From 1305b6e5c0209a82b524a509ff53ef72089e59b2 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Sun, 31 Jul 2022 22:37:40 -0500 Subject: [PATCH 19/28] add sitemap to new theme --- docs/source/conf.py | 14 +++++++++----- requirements.txt | 2 +- 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 62f24c2c..61b5c1f3 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -53,8 +53,10 @@ 'sphinx.ext.todo', 'sphinx.ext.extlinks', - # Add theme as extension so sitemap.xml is generated - 'sphinx_rtd_theme' + # theme is provided as an extension + "sphinx_rtd_theme", + # this generates sitemap.xml + "sphinx_sitemap", ] # Add any paths that contain templates here, relative to this directory. @@ -219,9 +221,11 @@ def previous_version(ver): "js/rtd_theme_overrides.js", ] -if "READTHEDOCS" not in os.environ: - # set the canonical url to our custom domain unless testing on RTD - html_baseurl = info.base_url +# set the canonical url to our custom domain (required for sitemap generation) +html_baseurl = info.base_url +sitemap_filename = "sitemap.xml" +# sitemap_url_scheme = "{lang}{version}{link}" +sitemap_url_scheme = "{version}{link}" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] diff --git a/requirements.txt b/requirements.txt index e69ae5c1..57410f63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,6 @@ docutils==0.16.0 sphinx>=2.4.4,<3.0 sphinx-autobuild -sphinx-sitemap==2.1.0 +sphinx-sitemap==2.2.0 sphinx-rtd-theme==1.0.0 jinja2<3.1 From 7b699ec9b27bc62960a53b4bf565bea31fa0f83a Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 2 Aug 2022 22:13:38 -0500 Subject: [PATCH 20/28] fix template --- docs/source/_templates/{version_menu.html => layout.html} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename docs/source/_templates/{version_menu.html => layout.html} (100%) diff --git a/docs/source/_templates/version_menu.html b/docs/source/_templates/layout.html similarity index 100% rename from docs/source/_templates/version_menu.html rename to docs/source/_templates/layout.html From 21de430635217dcb2d30ea6b19437f2e7942aada Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 2 Aug 2022 22:34:57 -0500 Subject: [PATCH 21/28] better sitemap --- docs/source/conf.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 61b5c1f3..e49cb246 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -224,8 +224,10 @@ def previous_version(ver): # set the canonical url to our custom domain (required for sitemap generation) html_baseurl = info.base_url sitemap_filename = "sitemap.xml" -# sitemap_url_scheme = "{lang}{version}{link}" -sitemap_url_scheme = "{version}{link}" +if "READTHEDOCS" in os.environ: + sitemap_url_scheme = "{lang}{version}{link}" +else: + sitemap_url_scheme = "{version}{link}" # Add any paths that contain custom themes here, relative to this directory. # html_theme_path = [] From 512f6fca1fe91976d39edbb431c6ffffe1edfce7 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 12:47:36 -0500 Subject: [PATCH 22/28] fix locally rendered versions menu --- docs/source/_static/css/rtd_theme_overrides.css | 3 +++ docs/source/_templates/layout.html | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 0c6ec0a6..697e6b88 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -2,6 +2,9 @@ .wy-nav-content { max-width: none; /* was 800px */ } +.wy-nav-side { + padding-bottom: 2.75em; +} /* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ .btn { diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html index 33ee6414..9a7ac6fb 100644 --- a/docs/source/_templates/layout.html +++ b/docs/source/_templates/layout.html @@ -15,7 +15,7 @@ {%- if not READTHEDOCS %}
- Read the Docs + v: {{ current_version }} @@ -26,12 +26,14 @@
{{ slug }}
{% endfor %} + {% if downloads %}
{{ _('Downloads') }}
{% for type, url in downloads %}
{{ type }}
{% endfor %}
+ {% endif %}
{%- endif %} From fef7c8be71fe22aa85f4a2937d5384af3f55e3e2 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 13:13:58 -0500 Subject: [PATCH 23/28] fix latest/ sitemap --- docs/source/conf.py | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index e49cb246..92983750 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -226,6 +226,9 @@ def previous_version(ver): sitemap_filename = "sitemap.xml" if "READTHEDOCS" in os.environ: sitemap_url_scheme = "{lang}{version}{link}" +elif "dev" in version: + # use latest/ instead of 3.8dev/ + sitemap_url_scheme = "latest/{link}" else: sitemap_url_scheme = "{version}{link}" From 62eab8421f44ee5d6352c9ab79d0ad85474dfdf3 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 15:14:46 -0500 Subject: [PATCH 24/28] copy RTD override for menu flyout --- docs/source/_static/css/rtd_theme_overrides.css | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/source/_static/css/rtd_theme_overrides.css b/docs/source/_static/css/rtd_theme_overrides.css index 697e6b88..8fb7c0c6 100644 --- a/docs/source/_static/css/rtd_theme_overrides.css +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -2,8 +2,9 @@ .wy-nav-content { max-width: none; /* was 800px */ } -.wy-nav-side { - padding-bottom: 2.75em; +/* Fix for nav bottom padding with flyout */ +nav.wy-nav-side { + padding-bottom: 3em; } /* $base-font-family: Lato,proxima-nova,Helvetica Neue,Arial,sans-serif; */ From e15f07e6a4718a8af32445cda9293ea4753900de Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 7 Feb 2023 15:51:51 -0600 Subject: [PATCH 25/28] Add support for building docs on ReadTheDocs This is basically a squashed commit of what was left from the rtd branch --- .readthedocs.yaml | 63 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 .readthedocs.yaml diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 00000000..a64c6e8d --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,63 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Declare the Python requirements required to build docs +python: + install: + - requirements: requirements.txt + # st2/ is st2.git cloned in post_checkout job + - requirements: st2/requirements.txt + +# Set the version of Python and other tools, and customize the build process +build: + os: ubuntu-20.04 + tools: + # python: "3.6" + python: "3.8" + apt_packages: + - python3-dev + - libldap2-dev + - libsasl2-dev + + # https://docs.readthedocs.io/en/stable/build-customization.html#extend-the-build-process + # NOTE: use " instead of ' for all quoting or RTD gives some weird errors. + jobs: + post_checkout: + - ./scripts/clone-st2.sh + - ./scripts/clone-orquesta.sh + + # We can't control the version of pip installed because it is part of the `install` stage. + #pre_install: + # # switch to version of pip from cloned copy of st2 + # - > + # export PIP_VERSION=$(grep "PIP_VERSION ?= " st2/Makefile | awk "{ print \$3 }"); + # echo PIP_VERSION=${PIP_VERSION}; + # pip install --upgrade "pip==${PIP_VERSION}"; + + # install: see python.install above + + post_install: + - cd ./st2; make virtualenv + - cd ./st2; make requirements + # generate-runner-parameters-documentation.py needs this in the st2 virtualenv + - . st2/virtualenv/bin/activate; pip install pytablewriter + + pre_build: + - . st2/virtualenv/bin/activate; ./scripts/generate-runner-parameters-documentation.py + - . st2/virtualenv/bin/activate; ./scripts/generate-internal-triggers-table.py + - . st2/virtualenv/bin/activate; ./scripts/generate-available-permission-types-table.py + +# Build documentation in the docs/ directory with Sphinx +sphinx: + builder: html + configuration: docs/source/conf.py + fail_on_warning: true + +# If using Sphinx, optionally build your docs in additional formats such as PDF +# formats: +# - pdf + From 600edee349decaddb237784cbed10b40476a2175 Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Wed, 3 Aug 2022 15:32:22 -0500 Subject: [PATCH 26/28] improve RTD sitemap --- docs/source/conf.py | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 92983750..a5f805cc 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -225,7 +225,13 @@ def previous_version(ver): html_baseurl = info.base_url sitemap_filename = "sitemap.xml" if "READTHEDOCS" in os.environ: - sitemap_url_scheme = "{lang}{version}{link}" + if "dev" in version and os.environ["READTHEDOCS_VERSION_TYPE"] != "external": + # use latest/ instead of 3.8dev/ unless this is external (ie a PR) + _sitemap_version = os.environ["READTHEDOCS_VERSION"] + "/" + else: + # prefer 3.7/ over stable/ in sitemap + _sitemap_version = "{version}" + sitemap_url_scheme = "{lang}" + _sitemap_version + "{link}" elif "dev" in version: # use latest/ instead of 3.8dev/ sitemap_url_scheme = "latest/{link}" From 77ca9a69986ba53d0ac73caddfc6a6bbff88e0df Mon Sep 17 00:00:00 2001 From: Jacob Floyd Date: Tue, 7 Feb 2023 15:13:30 -0600 Subject: [PATCH 27/28] Fix broken "3.9dev" link in versions menu Always use "3.9dev" instead of latest in the menu. --- docs/source/conf.py | 28 +++++++++++++++++++++++----- 1 file changed, 23 insertions(+), 5 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index a5f805cc..2a97a135 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -103,6 +103,7 @@ def previous_version(ver): # The short versions of two previous releases, e.g. 0.8 and 0.7 version_minus_1 = previous_version(version) version_minus_2 = previous_version(version_minus_1) +version_minus_3 = previous_version(version_minus_2) # extlink configurator sphinx.ext.extlinks extlinks = { @@ -324,13 +325,30 @@ def previous_version(ver): } if "READTHEDOCS" not in os.environ: - # READTHEDOCS handles versions for us. TODO: is this needed locally with the new theme? - html_context['versions'] = [ - ('latest', '%slatest' % info.base_url), - (version, '%s%s' % (info.base_url, version)), + # This is for local and GHA builds. Otherwise READTHEDOCS handles versions. + # the versions menu should always be: dev, stable, stable-1, stable-2 + versions = [] + if "dev" in version: + # show the "3.9dev" in the menu, even though "latest" is in the URL. + versions.append((version, '%slatest' % info.base_url)) + else: + _version = version.split(".") + dev_version = "%s.%sdev" % (_version[0], int(_version[1]) + 1) + versions.extend([ + (dev_version, "%slatest" % info.base_url), + # this is the stable version + (version, "%s%s" % (info.base_url, version)), + ]) + + versions.extend([ (version_minus_1, '%s%s' % (info.base_url, version_minus_1)), (version_minus_2, '%s%s' % (info.base_url, version_minus_2)), - ] + ]) + + if "dev" in version: + # this is the stable-2 version + versions.append((version_minus_3, '%s%s' % (info.base_url, version_minus_3))) + html_context['versions'] = versions html_context['current_version'] = version From 0700102a47955243c98d8268c686f2787ec3ab1d Mon Sep 17 00:00:00 2001 From: Carlos Date: Mon, 16 Jun 2025 09:24:13 +0200 Subject: [PATCH 28/28] [v3.8] Use version in installation url. --- docs/source/install/index.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/install/index.rst b/docs/source/install/index.rst index 94507d34..e67cace9 100644 --- a/docs/source/install/index.rst +++ b/docs/source/install/index.rst @@ -56,7 +56,7 @@ on Ubuntu, or ``sudo yum install curl nss`` on RHEL/RockyLinux/CentOS. Then run .. code-block:: bash - bash <(curl -sSL https://stackstorm.com/packages/install.sh) --user=st2admin --password=Ch@ngeMe + bash <(curl -sSL https://stackstorm.com/packages/v3.8/install.sh) --user=st2admin --password=Ch@ngeMe This is an opinionated installation of |st2|. It will download and install all components, as per the :doc:`single host reference deployment <./overview>`. It assumes that you have a clean, basic