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 + 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..8fb7c0c6 --- /dev/null +++ b/docs/source/_static/css/rtd_theme_overrides.css @@ -0,0 +1,86 @@ +/* layout changes */ +.wy-nav-content { + max-width: none; /* was 800px */ +} +/* 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; */ +.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 + * 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; + + /* 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/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; +} 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/_static/images/favicon.ico b/docs/source/_static/images/favicon.ico new file mode 100644 index 00000000..64880c4f Binary files /dev/null and b/docs/source/_static/images/favicon.ico differ diff --git a/docs/source/_static/images/logo.svg b/docs/source/_static/images/logo.svg new file mode 100644 index 00000000..a8cca473 --- /dev/null +++ b/docs/source/_static/images/logo.svg @@ -0,0 +1,17 @@ + + + + + + + + + + + + + + + + + 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..9bd64424 --- /dev/null +++ b/docs/source/_static/js/rtd_theme_overrides.js @@ -0,0 +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/_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); + }); +})() diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html new file mode 100644 index 00000000..9a7ac6fb --- /dev/null +++ b/docs/source/_templates/layout.html @@ -0,0 +1,40 @@ +{%- 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 %} +
+ + + v: {{ current_version }} + + +
+
+
{{ _('Versions') }}
+ {% for slug, url in versions %} +
{{ slug }}
+ {% endfor %} +
+ {% if downloads %} +
+
{{ _('Downloads') }}
+ {% for type, url in downloads %} +
{{ type }}
+ {% endfor %} +
+ {% endif %} +
+
+ {%- endif %} +{%- endblock %} diff --git a/docs/source/conf.py b/docs/source/conf.py index b774253f..2a97a135 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__ @@ -51,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. @@ -99,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 = { @@ -197,13 +202,45 @@ def previous_version(ver): # 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 + # 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, + "style_external_links": True, + "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", +] + +# set the canonical url to our custom domain (required for sitemap generation) +html_baseurl = info.base_url +sitemap_filename = "sitemap.xml" +if "READTHEDOCS" in os.environ: + 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}" +else: + sitemap_url_scheme = "{version}{link}" + # 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". @@ -214,12 +251,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, @@ -278,23 +315,41 @@ 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), - (version, '%s%s' % (info.base_url, version)), +} + +if "READTHEDOCS" not in os.environ: + # 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)), - ], - 'current_version': version, - 'css_files': [ - '_static/theme_overrides.css', - ], -} + ]) + + 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 # -- Options for LaTeX output --------------------------------------------- diff --git a/docs/source/info.py b/docs/source/info.py index 28f47aac..f487100b 100644 --- a/docs/source/info.py +++ b/docs/source/info.py @@ -9,11 +9,11 @@ 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/' +base_url = "https://docs.stackstorm.com/" htmlhelp_basename = 'StackStormDoc' man_pages = [ @@ -30,8 +30,6 @@ 'Miscellaneous'), ] -github_user = 'StackStorm' -github_repo = 'st2docs' -github_version = 'master' - -theme_base_url = u'https://docs.stackstorm.com/' +github_user = "StackStorm" +github_repo = "st2docs" +github_version = "master" 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 diff --git a/requirements.txt b/requirements.txt index 99b729ac..57410f63 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,5 +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 diff --git a/version.txt b/version.txt index 2090923e..cc1923a4 100644 --- a/version.txt +++ b/version.txt @@ -1 +1 @@ -3.8dev +3.8