From 2799a0d1c974508ec4ac3efc0215f9efd61066b4 Mon Sep 17 00:00:00 2001 From: Kacper Rzetelski Date: Fri, 20 Oct 2023 13:55:38 +0200 Subject: [PATCH 1/2] Replace recommonmark with MyST-Parser in docs --- docs/poetry.lock | 112 +++++++++++++----- docs/pyproject.toml | 2 +- docs/source/conf.py | 16 ++- docs/source/exposing.md | 4 +- docs/source/generic.md | 31 +++-- docs/source/gke.md | 4 +- docs/source/multidc/eks.md | 10 +- docs/source/multidc/gke.md | 8 +- docs/source/multidc/multidc.md | 46 +++---- docs/source/support/must-gather.md | 12 +- .../support/troubleshooting/installation.md | 12 +- 11 files changed, 153 insertions(+), 104 deletions(-) diff --git a/docs/poetry.lock b/docs/poetry.lock index 6973f7132a6..98cca4758da 100644 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -178,20 +178,6 @@ files = [ {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"}, ] -[[package]] -name = "commonmark" -version = "0.9.1" -description = "Python parser for the CommonMark Markdown spec" -optional = false -python-versions = "*" -files = [ - {file = "commonmark-0.9.1-py2.py3-none-any.whl", hash = "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9"}, - {file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"}, -] - -[package.extras] -test = ["flake8 (==3.7.8)", "hypothesis (==3.55.3)"] - [[package]] name = "docutils" version = "0.18.1" @@ -294,6 +280,30 @@ importlib-metadata = {version = ">=4.4", markers = "python_version < \"3.10\""} docs = ["mdx-gh-links (>=0.2)", "mkdocs (>=1.5)", "mkdocs-gen-files", "mkdocs-literate-nav", "mkdocs-nature (>=0.6)", "mkdocs-section-index", "mkdocstrings[python]"] testing = ["coverage", "pyyaml"] +[[package]] +name = "markdown-it-py" +version = "3.0.0" +description = "Python port of markdown-it. Markdown parsing, done right!" +optional = false +python-versions = ">=3.8" +files = [ + {file = "markdown-it-py-3.0.0.tar.gz", hash = "sha256:e3f60a94fa066dc52ec76661e37c851cb232d92f9886b15cb560aaada2df8feb"}, + {file = "markdown_it_py-3.0.0-py3-none-any.whl", hash = "sha256:355216845c60bd96232cd8d8c40e8f9765cc86f46880e43a8fd22dc1a1a8cab1"}, +] + +[package.dependencies] +mdurl = ">=0.1,<1.0" + +[package.extras] +benchmarking = ["psutil", "pytest", "pytest-benchmark"] +code-style = ["pre-commit (>=3.0,<4.0)"] +compare = ["commonmark (>=0.9,<1.0)", "markdown (>=3.4,<4.0)", "mistletoe (>=1.0,<2.0)", "mistune (>=2.0,<3.0)", "panflute (>=2.3,<3.0)"] +linkify = ["linkify-it-py (>=1,<3)"] +plugins = ["mdit-py-plugins"] +profiling = ["gprof2dot"] +rtd = ["jupyter_sphinx", "mdit-py-plugins", "myst-parser", "pyyaml", "sphinx", "sphinx-copybutton", "sphinx-design", "sphinx_book_theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + [[package]] name = "markupsafe" version = "2.1.3" @@ -363,6 +373,62 @@ files = [ {file = "MarkupSafe-2.1.3.tar.gz", hash = "sha256:af598ed32d6ae86f1b747b82783958b1a4ab8f617b06fe68795c7f026abbdcad"}, ] +[[package]] +name = "mdit-py-plugins" +version = "0.4.0" +description = "Collection of plugins for markdown-it-py" +optional = false +python-versions = ">=3.8" +files = [ + {file = "mdit_py_plugins-0.4.0-py3-none-any.whl", hash = "sha256:b51b3bb70691f57f974e257e367107857a93b36f322a9e6d44ca5bf28ec2def9"}, + {file = "mdit_py_plugins-0.4.0.tar.gz", hash = "sha256:d8ab27e9aed6c38aa716819fedfde15ca275715955f8a185a8e1cf90fb1d2c1b"}, +] + +[package.dependencies] +markdown-it-py = ">=1.0.0,<4.0.0" + +[package.extras] +code-style = ["pre-commit"] +rtd = ["myst-parser", "sphinx-book-theme"] +testing = ["coverage", "pytest", "pytest-cov", "pytest-regressions"] + +[[package]] +name = "mdurl" +version = "0.1.2" +description = "Markdown URL utilities" +optional = false +python-versions = ">=3.7" +files = [ + {file = "mdurl-0.1.2-py3-none-any.whl", hash = "sha256:84008a41e51615a49fc9966191ff91509e3c40b939176e643fd50a5c2196b8f8"}, + {file = "mdurl-0.1.2.tar.gz", hash = "sha256:bb413d29f5eea38f31dd4754dd7377d4465116fb207585f97bf925588687c1ba"}, +] + +[[package]] +name = "myst-parser" +version = "2.0.0" +description = "An extended [CommonMark](https://spec.commonmark.org/) compliant parser," +optional = false +python-versions = ">=3.8" +files = [ + {file = "myst_parser-2.0.0-py3-none-any.whl", hash = "sha256:7c36344ae39c8e740dad7fdabf5aa6fc4897a813083c6cc9990044eb93656b14"}, + {file = "myst_parser-2.0.0.tar.gz", hash = "sha256:ea929a67a6a0b1683cdbe19b8d2e724cd7643f8aa3e7bb18dd65beac3483bead"}, +] + +[package.dependencies] +docutils = ">=0.16,<0.21" +jinja2 = "*" +markdown-it-py = ">=3.0,<4.0" +mdit-py-plugins = ">=0.4,<1.0" +pyyaml = "*" +sphinx = ">=6,<8" + +[package.extras] +code-style = ["pre-commit (>=3.0,<4.0)"] +linkify = ["linkify-it-py (>=2.0,<3.0)"] +rtd = ["ipython", "pydata-sphinx-theme (==v0.13.0rc4)", "sphinx-autodoc2 (>=0.4.2,<0.5.0)", "sphinx-book-theme (==1.0.0rc2)", "sphinx-copybutton", "sphinx-design2", "sphinx-pyscript", "sphinx-tippy (>=0.3.1)", "sphinx-togglebutton", "sphinxext-opengraph (>=0.8.2,<0.9.0)", "sphinxext-rediraffe (>=0.2.7,<0.3.0)"] +testing = ["beautifulsoup4", "coverage[toml]", "pytest (>=7,<8)", "pytest-cov", "pytest-param-files (>=0.3.4,<0.4.0)", "pytest-regressions", "sphinx-pytest"] +testing-docutils = ["pygments", "pytest (>=7,<8)", "pytest-param-files (>=0.3.4,<0.4.0)"] + [[package]] name = "packaging" version = "23.2" @@ -447,22 +513,6 @@ files = [ {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, ] -[[package]] -name = "recommonmark" -version = "0.7.1" -description = "A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects." -optional = false -python-versions = "*" -files = [ - {file = "recommonmark-0.7.1-py2.py3-none-any.whl", hash = "sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f"}, - {file = "recommonmark-0.7.1.tar.gz", hash = "sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67"}, -] - -[package.dependencies] -commonmark = ">=0.8.1" -docutils = ">=0.11" -sphinx = ">=1.3.1" - [[package]] name = "redirects-cli" version = "0.1.3" @@ -935,4 +985,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = "^3.9" -content-hash = "d4653d93cdddedea0568c5d7db0337c936d5175db12b3b85aab85dba23dd88ed" +content-hash = "e0248c1388b9f21999f84243a001f61840e118b3340dd1be9f1faa3efb928b19" diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 68d2be4581b..756762511de 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -9,7 +9,6 @@ authors = ["ScyllaDB Documentation Contributors"] python = "^3.9" pyyaml = "6.0.1" pygments = "2.15.1" -recommonmark = "^0.7.1" sphinx-scylladb-theme = "~1.6.1" sphinx-sitemap = "2.5.1" sphinx-autobuild = "2021.3.14" @@ -17,6 +16,7 @@ Sphinx = "7.2.6" sphinx-multiversion-scylla = "~0.3.1" sphinx-markdown-tables = "~0.0.17" redirects_cli ="~0.1.3" +myst-parser = "^2.0.0" [build-system] requires = ["poetry>=0.12"] diff --git a/docs/source/conf.py b/docs/source/conf.py index 9e29ada1730..10a8dd64d19 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,7 +1,6 @@ # -*- coding: utf-8 -*- from datetime import date -from recommonmark.transform import AutoStructify from sphinx_scylladb_theme.utils import multiversion_regex_builder # -- General configuration @@ -16,9 +15,9 @@ 'sphinx.ext.extlinks', 'sphinx_scylladb_theme', 'sphinx_multiversion', - 'recommonmark', 'sphinx_markdown_tables', "sphinx_sitemap", + "myst_parser", ] # The suffix(es) of source filenames. @@ -50,13 +49,12 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True -# Setup Sphinx -def setup(sphinx): - sphinx.add_config_value('recommonmark_config', { - 'enable_eval_rst': True, - 'enable_auto_toc_tree': False, - }, True) - sphinx.add_transform(AutoStructify) +# -- Options for myst parser ---------------------------------------- + +myst_enable_extensions = ["colon_fence"] +# TODO: https://github.com/scylladb/scylla-operator/issues/1421 +# TODO: https://github.com/scylladb/scylla-operator/issues/1422 +suppress_warnings = ["myst.xref_missing", "myst.header"] # -- Options for not found extension ------------------------------------------- diff --git a/docs/source/exposing.md b/docs/source/exposing.md index c9136e3bdfd..38026fa1a01 100644 --- a/docs/source/exposing.md +++ b/docs/source/exposing.md @@ -3,9 +3,9 @@ This document explains how ScyllaDB Operator exposes ScyllaClusters in different network setups. A ScyllaCluster can be exposed in various network configurations, independently to clients and nodes. -``` note:: +:::{note} ScyllaClusters can be only exposed when the ScyllaDB version used version is `>=2023.1` ScyllaDB Enterprise or `>=5.2` ScyllaDB Open Source. -``` +::: ## Expose Options diff --git a/docs/source/generic.md b/docs/source/generic.md index 42380466a93..d2b26fd16fd 100644 --- a/docs/source/generic.md +++ b/docs/source/generic.md @@ -250,17 +250,17 @@ kubectl create configmap scylla-config -n scylla --from-file=/tmp/scylla.yaml -- ``` The operator will then apply the overridable properties `prefer_local` and `dc_suffix` if they are available in the provided mounted file. -``` note:: - If you want to enable authentication, you first need to adjust ``system_auth`` keyspace replication factor to the number of nodes in the datacenter via cqlsh. It allows you to ensure that the user’s information is kept highly available for the cluster. If ``system_auth`` is not equal to the number of nodes and a node fails, the user whose information is on that node will be denied access. - For production environments only use ``NetworkTopologyStrategy``. +:::{note} +If you want to enable authentication, you first need to adjust `system_auth` keyspace replication factor to the number of nodes in the datacenter via cqlsh. It allows you to ensure that the user’s information is kept highly available for the cluster. If `system_auth` is not equal to the number of nodes and a node fails, the user whose information is on that node will be denied access. +For production environments only use `NetworkTopologyStrategy`. - .. code-block:: console - - kubectl -n scylla exec -it pods/simple-cluster-us-east-1-us-east-1a-0 -c scylla -- cqlsh -e "ALTER KEYSPACE system_auth WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'us-east-1' : };" - - You can read more about enabling authentication in the `Enable authentication `_ section of ScyllaDB's documentation. +```shell +kubectl -n scylla exec -it pods/simple-cluster-us-east-1-us-east-1a-0 -c scylla -- cqlsh -e "ALTER KEYSPACE system_auth WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'us-east-1' : };" ``` +You can read more about enabling authentication in the [Enable authentication](https://opensource.docs.scylladb.com/stable/operating-scylla/security/authentication.html) section of ScyllaDB's documentation. +::: + ## Configure Scylla Manager Agent The operator creates a second container for each scylla instance that runs [Scylla Manager Agent](https://hub.docker.com/r/scylladb/scylla-manager-agent). @@ -299,17 +299,16 @@ Having edited and saved the yaml, you can check your cluster's Status and Events kubectl -n scylla describe scyllaclusters.scylla.scylladb.com/simple-cluster ``` -``` note:: - If you have configured ScyllaDB with ``authenticator`` set to ``PasswordAuthenticator``, you need to manually configure the replication factor of the ``system_auth`` keyspace with every scaling operation. - - .. code-block:: console +:::{note} +If you have configured ScyllaDB with `authenticator` set to `PasswordAuthenticator`, you need to manually configure the replication factor of the `system_auth` keyspace with every scaling operation. - kubectl -n scylla exec -it pods/simple-cluster-us-east-1-us-east-1a-0 -c scylla -- cqlsh -u -p -e "ALTER KEYSPACE system_auth WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'us-east-1' : };" - - - It is recommended to set ``system_auth`` replication factor to the number of nodes in each datacenter. +```shell +kubectl -n scylla exec -it pods/simple-cluster-us-east-1-us-east-1a-0 -c scylla -- cqlsh -u -p -e "ALTER KEYSPACE system_auth WITH REPLICATION = {'class' : 'NetworkTopologyStrategy', 'us-east-1' : };" ``` +It is recommended to set `system_auth` replication factor to the number of nodes in each datacenter. +::: + ## Benchmark with cassandra-stress After deploying our cluster along with the monitoring, we can benchmark it using cassandra-stress and see its performance in Grafana. We have a mini cli that generates Kubernetes Jobs that run cassandra-stress against a cluster. diff --git a/docs/source/gke.md b/docs/source/gke.md index 11b9804e874..bb61d77d436 100644 --- a/docs/source/gke.md +++ b/docs/source/gke.md @@ -23,7 +23,9 @@ cd examples/gke # ./gke.sh -u yanniszark@arrikto.com -p gke-demo-226716 -z us-west1-b ``` -:warning: Make sure to pass a ZONE (ex.: us-west1-b) and not a REGION (ex.: us-west1) or it will deploy nodes in each ZONE available in the region. +:::{warning} +Make sure to pass a ZONE (ex.: us-west1-b) and not a REGION (ex.: us-west1) or it will deploy nodes in each ZONE available in the region. +::: After you deploy, see how you can [benchmark your cluster with cassandra-stress](#benchmark-with-cassandra-stress). diff --git a/docs/source/multidc/eks.md b/docs/source/multidc/eks.md index bdba26668f6..266dd7d3a4d 100644 --- a/docs/source/multidc/eks.md +++ b/docs/source/multidc/eks.md @@ -41,7 +41,7 @@ nodeGroups: ``` Specify the first cluster's configuration file and save it as `cluster-us-east-1.yaml`. -Refer to [Creating an EKS cluster](../../eks#creating-an-eks-cluster) section of ScyllaDB Operator documentation for the reference of the configuration of node groups. +Refer to [Creating an EKS cluster](../eks.md#creating-an-eks-cluster) section of ScyllaDB Operator documentation for the reference of the configuration of node groups. To deploy the first cluster, use the below command: ```shell @@ -66,15 +66,15 @@ Once the cluster is ready, refer to [Deploying Scylla on a Kubernetes Cluster](. #### Prepare nodes for running ScyllaDB -Then, prepare the nodes for running ScyllaDB workloads and deploy a volume provisioner following the steps described in [Deploying Scylla on EKS](../../eks#prerequisites) in ScyllaDB Operator documentation. +Then, prepare the nodes for running ScyllaDB workloads and deploy a volume provisioner following the steps described in [Deploying Scylla on EKS](../eks.md#prerequisites) in ScyllaDB Operator documentation. ### Create the second EKS cluster Below is the required specification for the second cluster. As was the case with the first cluster, the provided values are only exemplary and can be adjusted according to your needs. -``` caution:: - It is required that the VPCs of the two EKS clusters have non-overlapping IPv4 network ranges. -``` +:::{caution} +It is required that the VPCs of the two EKS clusters have non-overlapping IPv4 network ranges. +::: ```yaml apiVersion: eksctl.io/v1alpha5 diff --git a/docs/source/multidc/gke.md b/docs/source/multidc/gke.md index 9c353ed0d9c..b119d9e9b3b 100644 --- a/docs/source/multidc/gke.md +++ b/docs/source/multidc/gke.md @@ -48,9 +48,9 @@ gcloud compute networks subnets create scylladb-us-west1 \ --secondary-range='cluster=172.17.0.0/16,services=172.18.0.0/20' ``` -``` caution:: - It is required that the IPv4 address ranges of the subnets allocated for the GKE clusters do not overlap. -``` +:::{caution} +It is required that the IPv4 address ranges of the subnets allocated for the GKE clusters do not overlap. +::: Refer to [Create a VPC-native cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/alias-ips) and [Alias IP ranges](https://cloud.google.com/vpc/docs/alias-ip) in GKE documentation for more information about VPC native clusters and alias IP ranges. @@ -79,7 +79,7 @@ gcloud container clusters create scylladb-us-east1 \ --services-secondary-range-name=services ``` -Refer to [Creating a GKE cluster](../../gke#creating-a-gke-cluster) section of ScyllaDB Operator documentation for more information regarding the configuration and deployment of additional node pools, including the one dedicated for ScyllaDB nodes. +Refer to [Creating a GKE cluster](../gke.md#creating-a-gke-cluster) section of ScyllaDB Operator documentation for more information regarding the configuration and deployment of additional node pools, including the one dedicated for ScyllaDB nodes. You will need to get the cluster's context for future operations. To do so, use the below command: ```shell diff --git a/docs/source/multidc/multidc.md b/docs/source/multidc/multidc.md index cbcf9149d4a..353f50ce787 100644 --- a/docs/source/multidc/multidc.md +++ b/docs/source/multidc/multidc.md @@ -4,10 +4,10 @@ This document describes the process of deploying a Multi Datacenter ScyllaDB clu This guide will walk you through the example procedure of deploying two datacenters in distinct regions of a selected cloud provider. -``` note:: - This guide is dedicated to deploying multi-datacenter ScyllaDB clusters and does not discuss unrelated configuration options. - For details of ScyllaDB cluster deployments and their configuration, refer to `Deploying Scylla on a Kubernetes Cluster <../generic.md>`_ in ScyllaDB Operator documentation. -``` +:::{note} +This guide is dedicated to deploying multi-datacenter ScyllaDB clusters and does not discuss unrelated configuration options. +For details of ScyllaDB cluster deployments and their configuration, refer to [Deploying Scylla on a Kubernetes Cluster](../generic.md) in ScyllaDB Operator documentation. +::: ## Prerequisites @@ -30,13 +30,13 @@ See [Install Tools](https://kubernetes.io/docs/tasks/tools/) in Kubernetes docum In v1.11, ScyllaDB Operator introduced support for manual multi-datacenter ScyllaDB cluster deployments. -``` warning:: - ScyllaDB Operator only supports *manual configuration* of multi-datacenter ScyllaDB clusters. - In other words, although ScyllaCluster API exposes the machinery necessary for setting up multi-datacenter ScylaDB clusters, the ScyllaDB Operator only automates operations for a single datacenter. +:::{warning} +ScyllaDB Operator only supports *manual configuration* of multi-datacenter ScyllaDB clusters. +In other words, although ScyllaCluster API exposes the machinery necessary for setting up multi-datacenter ScylaDB clusters, the ScyllaDB Operator only automates operations for a single datacenter. - Operations related to multiple datacenters may require manual intervention of a human operator. - Most notably, destroying one of the Kubernetes clusters or ScyllaDB datacenters is going to leave DN nodes behind in other datacenters, and their removal has to be carried out manually. -``` +Operations related to multiple datacenters may require manual intervention of a human operator. +Most notably, destroying one of the Kubernetes clusters or ScyllaDB datacenters is going to leave DN nodes behind in other datacenters, and their removal has to be carried out manually. +::: The main mechanism used to set up a manual multi-datacenter ScyllaDB cluster is a field in ScyllaCluster's specification - `externalSeeds`. @@ -92,12 +92,12 @@ kubectl --context="${CONTEXT_DC1}" create ns scylla For this guide, let's assume that your cluster is running in `us-east-1` region and the nodes dedicated to running ScyllaDB nodes are running in zones `us-east-1a`, `us-east-1b` and `us-east-1c` correspondingly. If that is not the case, adjust the manifest accordingly. -``` caution:: - The ``.spec.name`` field of the ScyllaCluster objects represents the ScyllaDB cluster name and has to be consistent across all datacenters of this ScyllaDB cluster. - The names of the datacenters, specified in ``.spec.datacenter.name``, have to be unique across the entire multi-datacenter cluster. - - For more information see `Create a ScyllaDB Cluster - Multi Data Centers (DC) `_ in ScyllaDB documentation. -``` +:::{caution} +The `.spec.name` field of the ScyllaCluster objects represents the ScyllaDB cluster name and has to be consistent across all datacenters of this ScyllaDB cluster. +The names of the datacenters, specified in `.spec.datacenter.name`, have to be unique across the entire multi-datacenter cluster. + +For more information see [Create a ScyllaDB Cluster - Multi Data Centers (DC)](https://opensource.docs.scylladb.com/stable/operating-scylla/procedures/cluster-management/create-cluster-multidc.html) in ScyllaDB documentation. +::: Save the ScyllaCluster manifest in `dc1.yaml`: ```yaml @@ -304,13 +304,13 @@ UN 10.0.19.237 107 KB 256 ? 64b6292a-327f-4128-852a-6004039 ##### Retrieve PodIPs of ScyllaDB nodes for use as external seeds -``` warning:: - Due to the ephemeral nature of PodIPs, it is ill-advised to use them as seeds in production environments. - This is because there is a high likelihood that the Pods of your ScyllaDB clusters will change their IPs during the cluster's lifecycle, and so the provided seeds will no longer point to the ScyllaDB nodes. - It is undesired, as the seeds provided on node's startup may serve as fallback contact points when all of the node's peers are unreachable. - In production environments, it is recommended that you use domain names or non-ephemeral IP addresses as external seeds. - PodIPs are being used in this example for the sheer simplicity of this setup. -``` +:::{warning} +Due to the ephemeral nature of PodIPs, it is ill-advised to use them as seeds in production environments. +This is because there is a high likelihood that the Pods of your ScyllaDB clusters will change their IPs during the cluster's lifecycle, and so the provided seeds will no longer point to the ScyllaDB nodes. +It is undesired, as the seeds provided on node's startup may serve as fallback contact points when all of the node's peers are unreachable. +In production environments, it is recommended that you use domain names or non-ephemeral IP addresses as external seeds. +PodIPs are being used in this example for the sheer simplicity of this setup. +::: Use the below commands and their expected outputs as a reference for retrieving the PodIPs used by the cluster for inter-node communication. ```shell diff --git a/docs/source/support/must-gather.md b/docs/source/support/must-gather.md index 822451ab88e..7e0089084da 100644 --- a/docs/source/support/must-gather.md +++ b/docs/source/support/must-gather.md @@ -24,12 +24,12 @@ export KUBECONFIG=~/.kube/config ls -l "${KUBECONFIG}" ``` -```note:: +:::{note} There can be slight deviations in the arguments for your container tool, depending on the container runtime, whether you use SELinux or similar factors. As an example, the need for the `Z` option on volume mounts depends on whether you use SELinux and what context is applied on your file or directory. If you get an error mentioning `Error: lsetxattr : operation not supported`, try it without the `Z` option. -``` +::: Let's also check whether your kubeconfig uses [external authentication plugin](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#client-go-credential-plugins). You can determine that by running @@ -63,9 +63,9 @@ kubectl config view --minify --raw -o yaml | yq -e '.users[0].user = {"token": e KUBECONFIG="${kubeconfig}" ``` -```note:: +:::{note} If you don't have `yq` installed, you can get it at https://github.com/mikefarah/yq/#install or you can replace the user authentication settings manually. -``` +::: ### Podman ```bash @@ -86,10 +86,10 @@ Unless you hit scale issues, we advise not to use this mode, as sometimes the Sc scylla-operator must-gather --namespace="" ``` -```note:: +:::{note} The `--namespace` flag affects only `ScyllaClusters`. Other resources related to the operator installation or cluster state will still be collected from other namespaces. -``` +::: ### Collecting every resource in the cluster diff --git a/docs/source/support/troubleshooting/installation.md b/docs/source/support/troubleshooting/installation.md index 226aa8c1d41..b93fcce7b51 100644 --- a/docs/source/support/troubleshooting/installation.md +++ b/docs/source/support/troubleshooting/installation.md @@ -6,23 +6,23 @@ Scylla Operator provides several custom API resources that use webhooks to funct Unfortunately, it is often the case that user's clusters have modified SDN, that doesn't extend to the control plane, and Kubernetes apiserver is not able to reach the pods that serve the webhook traffic. Another common case are firewall rules that block the webhook traffic. -```note:: +:::{note} To be called a Kubernetes cluster, clusters are required to pass Kubernetes conformance test suite. This suite includes tests that require Kubernetes apiserver to be able to reach webhook services. -``` +::: -```note:: +:::{note} Before filing an issue, please make sure your cluster webhook traffic can reach your webhook services, independently of Scylla Operator resources. -``` +::: ### EKS #### Custom CNI EKS is currently breaking Kubernetes webhooks [when used with custom CNI networking](https://github.com/aws/containers-roadmap/issues/1215). -```note:: +:::{note} We advise you to avoid using such setups and use a conformant Kubernetes cluster that supports webhooks. -``` +::: There are some workarounds where you can reconfigure the webhook to use Ingress or hostNetwork instead, but it's beyond a standard configuration that we support and not specific to the Scylla Operator. From 06f581bcc7fb3e400dccec8191c3c3c5b3c4b486 Mon Sep 17 00:00:00 2001 From: David Garcia Date: Tue, 31 Oct 2023 10:33:00 +0000 Subject: [PATCH 2/2] Add scylladb_markdown extension --- .gitignore | 1 + docs/poetry.lock | 32 ++++++++++++- docs/pyproject.toml | 1 + docs/source/_ext/scylladb_markdown.py | 65 +++++++++++++++++++++++++++ docs/source/conf.py | 22 +++++---- 5 files changed, 108 insertions(+), 13 deletions(-) create mode 100644 docs/source/_ext/scylladb_markdown.py diff --git a/.gitignore b/.gitignore index 45a077d8d9f..fe74f36cd87 100644 --- a/.gitignore +++ b/.gitignore @@ -18,3 +18,4 @@ examples/common/grafana/values.yaml # additions for docs docs/_build source/.doctrees +docs/**/*.pyc diff --git a/docs/poetry.lock b/docs/poetry.lock index 98cca4758da..1a33b8cfa75 100644 --- a/docs/poetry.lock +++ b/docs/poetry.lock @@ -178,6 +178,20 @@ files = [ {file = "colorama-0.4.6.tar.gz", hash = "sha256:08695f5cb7ed6e0531a20572697297273c47b8cae5a63ffc6d6ed5c201be6e44"}, ] +[[package]] +name = "commonmark" +version = "0.9.1" +description = "Python parser for the CommonMark Markdown spec" +optional = false +python-versions = "*" +files = [ + {file = "commonmark-0.9.1-py2.py3-none-any.whl", hash = "sha256:da2f38c92590f83de410ba1a3cbceafbc74fee9def35f9251ba9a971d6d66fd9"}, + {file = "commonmark-0.9.1.tar.gz", hash = "sha256:452f9dc859be7f06631ddcb328b6919c67984aca654e5fefb3914d54691aed60"}, +] + +[package.extras] +test = ["flake8 (==3.7.8)", "hypothesis (==3.55.3)"] + [[package]] name = "docutils" version = "0.18.1" @@ -513,6 +527,22 @@ files = [ {file = "PyYAML-6.0.1.tar.gz", hash = "sha256:bfdf460b1736c775f2ba9f6a92bca30bc2095067b8a9d77876d1fad6cc3b4a43"}, ] +[[package]] +name = "recommonmark" +version = "0.7.1" +description = "A docutils-compatibility bridge to CommonMark, enabling you to write CommonMark inside of Docutils & Sphinx projects." +optional = false +python-versions = "*" +files = [ + {file = "recommonmark-0.7.1-py2.py3-none-any.whl", hash = "sha256:1b1db69af0231efce3fa21b94ff627ea33dee7079a01dd0a7f8482c3da148b3f"}, + {file = "recommonmark-0.7.1.tar.gz", hash = "sha256:bdb4db649f2222dcd8d2d844f0006b958d627f732415d399791ee436a3686d67"}, +] + +[package.dependencies] +commonmark = ">=0.8.1" +docutils = ">=0.11" +sphinx = ">=1.3.1" + [[package]] name = "redirects-cli" version = "0.1.3" @@ -985,4 +1015,4 @@ testing = ["big-O", "jaraco.functools", "jaraco.itertools", "more-itertools", "p [metadata] lock-version = "2.0" python-versions = "^3.9" -content-hash = "e0248c1388b9f21999f84243a001f61840e118b3340dd1be9f1faa3efb928b19" +content-hash = "1113bd488fb8a8861be25b98c554a014f4434f6dd3644e9bacf4256817395da9" diff --git a/docs/pyproject.toml b/docs/pyproject.toml index 756762511de..895dba38624 100644 --- a/docs/pyproject.toml +++ b/docs/pyproject.toml @@ -17,6 +17,7 @@ sphinx-multiversion-scylla = "~0.3.1" sphinx-markdown-tables = "~0.0.17" redirects_cli ="~0.1.3" myst-parser = "^2.0.0" +recommonmark = "^0.7.1" [build-system] requires = ["poetry>=0.12"] diff --git a/docs/source/_ext/scylladb_markdown.py b/docs/source/_ext/scylladb_markdown.py new file mode 100644 index 00000000000..d849e43d1a5 --- /dev/null +++ b/docs/source/_ext/scylladb_markdown.py @@ -0,0 +1,65 @@ +import os +from recommonmark.transform import AutoStructify + +class BaseParser: + def __init__(self, app): + self.app = app + + def setup(self): + raise NotImplementedError + +class RecommonmarkParser(BaseParser): + def setup(self): + try: + self.app.setup_extension('recommonmark') + self.app.setup_extension('sphinx_markdown_tables') + + self.app.add_config_value('recommonmark_config', { + 'enable_eval_rst': True, + 'enable_auto_toc_tree': False, + }, True) + self.app.add_transform(AutoStructify) + except ImportError: + raise RuntimeError("recommonmark and sphinx_markdown_tables are not installed!") + +class MystParser(BaseParser): + def setup(self): + try: + self.app.setup_extension('myst_parser') + self.app.config.myst_enable_extensions = ["colon_fence"] + + # TODO: https://github.com/scylladb/scylla-operator/issues/1421 + # TODO: https://github.com/scylladb/scylla-operator/issues/1422 + self.app.config.suppress_warnings = ["myst.xref_missing", "myst.header"] + + except ImportError: + raise RuntimeError("myst-parser is not installed") + +def select_parser(app, config): + if not config.scylladb_markdown_enable: + return + + current_version = os.environ.get('SPHINX_MULTIVERSION_NAME', 'stable') + + config.source_suffix = { + '.rst': 'restructuredtext', + '.md': 'markdown', + } + + if current_version in config.scylladb_markdown_recommonmark_versions: + parser = RecommonmarkParser(app) + else: + parser = MystParser(app) + + parser.setup() + +def setup(app): + app.add_config_value('scylladb_markdown_enable', True, 'env') + app.add_config_value('scylladb_markdown_recommonmark_versions', [], 'env') + app.connect('config-inited', select_parser) + + return { + "version": "0.1", + "parallel_read_safe": True, + "parallel_write_safe": True, + } diff --git a/docs/source/conf.py b/docs/source/conf.py index 10a8dd64d19..427b957708d 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -1,7 +1,10 @@ # -*- coding: utf-8 -*- +import os +import sys from datetime import date from sphinx_scylladb_theme.utils import multiversion_regex_builder +sys.path.insert(0, os.path.abspath('./_ext')) # -- General configuration @@ -15,15 +18,13 @@ 'sphinx.ext.extlinks', 'sphinx_scylladb_theme', 'sphinx_multiversion', - 'sphinx_markdown_tables', "sphinx_sitemap", - "myst_parser", + "scylladb_markdown" ] # The suffix(es) of source filenames. # You can specify multiple suffix as a list of string: -# -source_suffix = ['.rst', '.md'] +source_suffix = ['.rst'] autosectionlabel_prefix_document = True # The encoding of source files. @@ -49,14 +50,7 @@ # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = True -# -- Options for myst parser ---------------------------------------- - -myst_enable_extensions = ["colon_fence"] -# TODO: https://github.com/scylladb/scylla-operator/issues/1421 -# TODO: https://github.com/scylladb/scylla-operator/issues/1422 -suppress_warnings = ["myst.xref_missing", "myst.header"] - -# -- Options for not found extension ------------------------------------------- +# -- Options for not found extension # Template used to render the 404.html generated by this extension. notfound_template = '404.html' @@ -69,6 +63,10 @@ # Read a YAML dictionary of redirections and generate an HTML file for each redirects_file = "./redirections.yaml" +# -- Options for markdown extension +scylladb_markdown_enable = True +scylladb_markdown_recommonmark_versions = ['v1.8', 'v1.9', 'v1.10', 'v1.11'] + # -- Options for multiversion extension # Whitelist pattern for tags (set to None to ignore all tags) TAGS = []