diff --git a/.circleci/config.yml b/.circleci/config.yml index 8108c9c..c6973e1 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -148,7 +148,7 @@ workflows: jobs: quickcheck-docs: docker: - - image: cimg/base:2020.08 + - image: cimg/base:2023.09 steps: - checkout - install-docdep @@ -279,7 +279,7 @@ jobs: publish-zrepl-github-io: docker: - - image: cimg/python:3.7 + - image: cimg/base:2023.09 steps: - checkout - invoke-lazy-sh: diff --git a/docs/Makefile b/docs/Makefile index f85e18e..9c1e66d 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -10,11 +10,11 @@ BUILDDIR = _build # Put it first so that "make" without argument is like "make help". help: - @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" -c sphinxconf $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) .PHONY: help Makefile # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" -c sphinxconf $(SPHINXOPTS) $(O) + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) diff --git a/docs/_static/banner.css b/docs/_static/banner.css new file mode 100644 index 0000000..ca37f0f --- /dev/null +++ b/docs/_static/banner.css @@ -0,0 +1,43 @@ +/* https://github.com/sphinx-contrib/sphinxcontrib-versioning/blob/0b56210959c6b21bbb730072e81876491b4e1371/sphinxcontrib/versioning/_static/banner.css */ + +.scv-banner { + padding: 3px; + border-radius: 2px; + font-size: 80%; + text-align: center; + color: white; + background: #d40 linear-gradient(-45deg, + rgba(255, 255, 255, 0.2) 0%, + rgba(255, 255, 255, 0.2) 25%, + transparent 25%, + transparent 50%, + rgba(255, 255, 255, 0.2) 50%, + rgba(255, 255, 255, 0.2) 75%, + transparent 75%, + transparent + ); + background-size: 28px 28px; +} +.scv-banner > a { + color: white; +} + + +.scv-sphinx_rtd_theme { + background-color: #2980B9; +} + + +.scv-bizstyle { + background-color: #336699; +} + + +.scv-classic { + text-align: center !important; +} + + +.scv-traditional { + text-align: center !important; +} diff --git a/docs/_templates/page.html b/docs/_templates/page.html new file mode 100644 index 0000000..daf3160 --- /dev/null +++ b/docs/_templates/page.html @@ -0,0 +1,17 @@ +{% extends "!page.html" %} +{% block body %} +{% if current_version and latest_version and current_version != latest_version %} +

+ + {% if current_version.is_released %} + You're reading an old version of this documentation. + If you want up-to-date information, please have a look at {{latest_version.name}}. + {% else %} + You're reading the documentation for a development version. + For the latest released version, please have a look at {{latest_version.name}}. + {% endif %} + +

+{% endif %} +{{ super() }} +{% endblock %}% diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 0000000..31a1257 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} diff --git a/docs/conf.py b/docs/conf.py deleted file mode 120000 index 03f0eff..0000000 --- a/docs/conf.py +++ /dev/null @@ -1 +0,0 @@ -sphinxconf/conf.py \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..28a9a41 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,187 @@ +#!/usr/bin/env python3 +# -*- coding: utf-8 -*- +# +# zrepl documentation build configuration file, created by +# sphinx-quickstart on Wed Nov 8 22:28:10 2017. +# +# This file is execfile()d with the current directory set to its +# containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +# 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. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + + +# -- General configuration ------------------------------------------------ + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = ['sphinx.ext.todo', + 'sphinx.ext.githubpages', + 'sphinx.ext.extlinks', + "sphinx_multiversion", +] + +# suppress_warnings = ['image.nonlocal_uri'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['./_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = 'zrepl' +copyright = '2017-2023, Christian Schwarz' +author = 'Christian Schwarz' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +#version = set by sphinxcontrib-versioning +# The full version, including alpha/beta/rc tags. +#release = version + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = 'en' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This patterns also effect to html_static_path and html_extra_path +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True + + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# 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 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_css_files = [ + 'banner.css', +] + +html_logo = '_static/zrepl.svg' + +html_context = { + # https://github.com/rtfd/sphinx_rtd_theme/issues/205 + # Add 'Edit on Github' link instead of 'View page source' + "display_github": True, + "github_user": "zrepl", + "github_repo": "zrepl", + "github_version": "master", + "conf_py_path": "/docs/", + "source_suffix": source_suffix, +} + +# -- Options for HTMLHelp output ------------------------------------------ + +# Output file base name for HTML help builder. +htmlhelp_basename = 'zrepldoc' + + +# -- Options for LaTeX output --------------------------------------------- + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'zrepl.tex', 'zrepl Documentation', + 'Christian Schwarz', 'manual'), +] + + +# -- Options for manual page output --------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'zrepl', 'zrepl Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'zrepl', 'zrepl Documentation', + author, 'zrepl', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Options for the extlinks extension ----------------------------------- +# http://www.sphinx-doc.org/en/stable/ext/extlinks.html +extlinks = { + 'issue':('https://github.com/zrepl/zrepl/issues/%s', 'issue #%s'), + 'repomasterlink':('https://github.com/zrepl/zrepl/blob/master/%s', '%s'), + 'sampleconf':('https://github.com/zrepl/zrepl/blob/master/config/samples%s', 'config/samples%s'), + 'commit':('https://github.com/zrepl/zrepl/commit/%s', 'commit %s'), + } + diff --git a/docs/publish.sh b/docs/publish.sh index 04e6932..2507719 100755 --- a/docs/publish.sh +++ b/docs/publish.sh @@ -26,8 +26,8 @@ checkout_repo_msg() { echo "clone ${GHPAGESREPO} to ${PUBLICDIR}:" } -if ! type sphinx-versioning >/dev/null; then - echo "install sphinx-versioning and come back" +if ! type sphinx-multiversion >/dev/null; then + echo "install sphinx-multiversion and come back" exit 1 fi @@ -49,11 +49,11 @@ else read -r fi -pushd "$PUBLICDIR" +pushd "$PUBLICDIR" echo "verify we're in the GitHub pages repo..." git remote get-url origin | grep -E "^${GHPAGESREPO}\$" -if [ "$?" -ne "0" ] ;then +if [ "$?" -ne "0" ] ;then checkout_repo_msg echo "finished checkout, please run again" exit 1 @@ -73,22 +73,15 @@ popd echo "building site" -flags="$(python3 gen-sphinx-versioning-flags.py)" -set -e -sphinx-versioning build \ - $flags \ - docs ./public_git \ - -- -c sphinxconf # older conf.py throw errors because they used - # version = subprocess.show_output(["git", "describe"]) - # which fails when building with sphinxcontrib-versioning -set +e +python3 run-sphinx-multiversion.py . ./public_git + CURRENT_COMMIT=$(git rev-parse HEAD) git status --porcelain if [[ "$(git status --porcelain)" != "" ]]; then - CURRENT_COMMIT="${CURRENT_COMMIT}(dirty)" + CURRENT_COMMIT="${CURRENT_COMMIT}(dirty)" fi -COMMIT_MSG="sphinx-versioning render from publish.sh - $(date -u) - ${CURRENT_COMMIT}" +COMMIT_MSG="render from publish.sh - $(date -u) - ${CURRENT_COMMIT}" pushd "$PUBLICDIR" diff --git a/docs/requirements.txt b/docs/requirements.txt index 81cf3cf..87a00c7 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,30 +1,24 @@ -alabaster==0.7.12 -attrs==19.1.0 -Babel==2.7.0 -certifi==2019.6.16 -chardet==3.0.4 -Click==7.0 -colorclass==2.2.0 -docutils==0.15.2 -idna==2.8 -imagesize==1.1.0 -Jinja2==2.10.1 -MarkupSafe==1.1.1 -packaging==19.1 -Pygments==2.4.2 -pyparsing==2.4.2 -pytz==2019.2 -requests==2.22.0 -six==1.12.0 -snowballstemmer==1.9.1 -Sphinx==1.8.5 -sphinx-rtd-theme==0.4.3 -sphinxcontrib-applehelp==1.0.1 -sphinxcontrib-devhelp==1.0.1 -sphinxcontrib-htmlhelp==1.0.2 +alabaster==0.7.13 +Babel==2.12.1 +certifi==2023.7.22 +charset-normalizer==3.2.0 +docutils==0.18.1 +idna==3.4 +imagesize==1.4.1 +Jinja2==3.1.2 +MarkupSafe==2.1.3 +packaging==23.1 +Pygments==2.16.1 +requests==2.31.0 +snowballstemmer==2.2.0 +Sphinx==7.2.5 +sphinx-multiversion @ git+https://github.com/zrepl/sphinx-multiversion/@52c915d7ad898d9641ec48c8bbccb7d4f079db93 +sphinx-rtd-theme==1.3.0 +sphinxcontrib-applehelp==1.0.7 +sphinxcontrib-devhelp==1.0.5 +sphinxcontrib-htmlhelp==2.0.4 +sphinxcontrib-jquery==4.1 sphinxcontrib-jsmath==1.0.1 -sphinxcontrib-qthelp==1.0.2 -sphinxcontrib-serializinghtml==1.1.3 -git+https://github.com/rwblair/sphinxcontrib-versioning.git@7e3885a389a809e17ea55261316b7b0e98dbf98f#egg=sphinxcontrib-versioning -sphinxcontrib-websupport==1.1.2 -urllib3==1.25.3 +sphinxcontrib-qthelp==1.0.6 +sphinxcontrib-serializinghtml==1.1.9 +urllib3==2.0.4 diff --git a/docs/gen-sphinx-versioning-flags.py b/docs/run-sphinx-multiversion.py similarity index 57% rename from docs/gen-sphinx-versioning-flags.py rename to docs/run-sphinx-multiversion.py index 5cea3cb..b57e7f7 100644 --- a/docs/gen-sphinx-versioning-flags.py +++ b/docs/run-sphinx-multiversion.py @@ -1,7 +1,15 @@ #!/usr/bin/env python3 +from pathlib import Path import subprocess import re +import argparse +import distutils + +argparser = argparse.ArgumentParser() +argparser.add_argument("docsroot") +argparser.add_argument("outdir") +args = argparser.parse_args() output = subprocess.run(["git", "tag", "-l"], capture_output=True, check=True, text=True) tagRE = re.compile(r"^v(?P\d+)\.(?P\d+)\.(?P\d+)(-rc(?P\d+))?$") @@ -27,8 +35,8 @@ for line in output.stdout.split("\n"): t = Tag() t.orig = line - t.major = int(m["major"]) - t.minor = int(m["minor"]) + t.major = int(m["major"]) + t.minor = int(m["minor"]) t.patch = int(m["patch"]) t.rc = int(m["rc"] if m["rc"] is not None else 0) @@ -49,26 +57,16 @@ for (mm, l) in by_major_minor.items(): latest_by_major_minor.append(l[-1]) latest_by_major_minor.sort(key=lambda tag: (tag.major, tag.minor)) -# print(by_major_minor) -# print(latest_by_major_minor) - -cmdline = [] - -for latest_patch in latest_by_major_minor: - cmdline.append("--whitelist-tags") - cmdline.append(f"^{re.escape(latest_patch.orig)}$") - -# we want flexibility to update docs for the latest stable release -# => we have a branch for that, called `stable` which we move manually -# TODO: in the future, have f"stable-{latest_by_major_minor[-1]}" -default_version = "stable" -cmdline.extend(["--whitelist-branches", default_version]) - -cmdline.extend(["--root-ref", f"{default_version}"]) -cmdline.extend(["--banner-main-ref", f"{default_version}"]) -cmdline.extend(["--show-banner"]) -cmdline.extend(["--sort", "semver"]) - -cmdline.extend(["--whitelist-branches", "master"]) - -print(" ".join(cmdline)) +cmdline = [ + "sphinx-multiversion", + "-D", "smv_tag_whitelist=^({})$".format("|".join([re.escape(tag.orig) for tag in latest_by_major_minor])), + "-D", "smv_branch_whitelist=^(master|stable)$", + "-D", "smv_remote_whitelist=^.*$", + "-D", "smv_latest_version=stable", + "-D", r"smv_released_pattern=^refs/(tags|heads|remotes/[^/]+)/(?!master).*$", # treat everything except master as released, that way, the banner message makes sense + # "--dump-metadata", # for debugging + args.docsroot, + args.outdir, +] +print(cmdline) +subprocess.run(cmdline, check=True) diff --git a/docs/sphinxconf/conf.py b/docs/sphinxconf/conf.py deleted file mode 100644 index 10281ec..0000000 --- a/docs/sphinxconf/conf.py +++ /dev/null @@ -1,182 +0,0 @@ -#!/usr/bin/env python3 -# -*- coding: utf-8 -*- -# -# zrepl documentation build configuration file, created by -# sphinx-quickstart on Wed Nov 8 22:28:10 2017. -# -# This file is execfile()d with the current directory set to its -# containing dir. -# -# Note that not all possible configuration values are present in this -# autogenerated file. -# -# All configuration values have a default; values that are commented out -# serve to show the default. - -# 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. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) - - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['sphinx.ext.todo', - 'sphinx.ext.githubpages', - 'sphinx.ext.extlinks'] - -suppress_warnings = ['image.nonlocal_uri'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['../_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -# source_suffix = ['.rst', '.md'] -source_suffix = '.rst' - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = 'zrepl' -copyright = '2017-2019, Christian Schwarz' -author = 'Christian Schwarz' - -# The version info for the project you're documenting, acts as replacement for -# |version| and |release|, also used in various other places throughout the -# built documents. -# -# The short X.Y version. -#version = set by sphinxcontrib-versioning -# The full version, including alpha/beta/rc tags. -#release = version - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -# -html_theme = 'sphinx_rtd_theme' - -# 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 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_logo = '../_static/zrepl.svg' - -html_context = { - # https://github.com/rtfd/sphinx_rtd_theme/issues/205 - # Add 'Edit on Github' link instead of 'View page source' - "display_github": True, - "github_user": "zrepl", - "github_repo": "zrepl", - "github_version": "master", - "conf_py_path": "/docs/", - "source_suffix": source_suffix, -} - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -htmlhelp_basename = 'zrepldoc' - - -# -- Options for LaTeX output --------------------------------------------- - -latex_elements = { - # The paper size ('letterpaper' or 'a4paper'). - # - # 'papersize': 'letterpaper', - - # The font size ('10pt', '11pt' or '12pt'). - # - # 'pointsize': '10pt', - - # Additional stuff for the LaTeX preamble. - # - # 'preamble': '', - - # Latex figure (float) alignment - # - # 'figure_align': 'htbp', -} - -# Grouping the document tree into LaTeX files. List of tuples -# (source start file, target name, title, -# author, documentclass [howto, manual, or own class]). -latex_documents = [ - (master_doc, 'zrepl.tex', 'zrepl Documentation', - 'Christian Schwarz', 'manual'), -] - - -# -- Options for manual page output --------------------------------------- - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'zrepl', 'zrepl Documentation', - [author], 1) -] - - -# -- Options for Texinfo output ------------------------------------------- - -# Grouping the document tree into Texinfo files. List of tuples -# (source start file, target name, title, author, -# dir menu entry, description, category) -texinfo_documents = [ - (master_doc, 'zrepl', 'zrepl Documentation', - author, 'zrepl', 'One line description of project.', - 'Miscellaneous'), -] - - -# -- Options for the extlinks extension ----------------------------------- -# http://www.sphinx-doc.org/en/stable/ext/extlinks.html -extlinks = { - 'issue':('https://github.com/zrepl/zrepl/issues/%s', 'issue #'), - 'repomasterlink':('https://github.com/zrepl/zrepl/blob/master/%s', ''), - 'sampleconf':('https://github.com/zrepl/zrepl/blob/master/config/samples%s', 'config/samples'), - 'commit':('https://github.com/zrepl/zrepl/commit/%s', 'commit '), - } -