diff --git a/HACKING.md b/HACKING.md index cd27ad5756..01217be328 100644 --- a/HACKING.md +++ b/HACKING.md @@ -419,4 +419,4 @@ $ eu-unstrip -n --core | awk '/scylla$/ { s=$2; sub(/@.*$/, "", s); p ### Core dump debugging -See [debugging.md](docs/guides/debugging.md). +See [debugging.md](docs/dev/debugging.md). diff --git a/README.md b/README.md index 287bb11f98..8b1e46c5ec 100644 --- a/README.md +++ b/README.md @@ -42,7 +42,7 @@ For further information, please see: * [Docker image build documentation] for information on how to build Docker images. [developer documentation]: HACKING.md -[build documentation]: docs/guides/building.md +[build documentation]: docs/dev/building.md [docker image build documentation]: dist/docker/debian/README.md ## Running Scylla @@ -65,7 +65,7 @@ $ ./tools/toolchain/dbuild ./build/release/scylla --help ## Testing -See [test.py manual](docs/guides/testing.md). +See [test.py manual](docs/dev/testing.md). ## Scylla APIs and compatibility By default, Scylla is compatible with Apache Cassandra and its APIs - CQL and @@ -73,12 +73,12 @@ Thrift. There is also support for the API of Amazon DynamoDB™, which needs to be enabled and configured in order to be used. For more information on how to enable the DynamoDB™ API in Scylla, and the current compatibility of this feature as well as Scylla-specific extensions, see -[Alternator](docs/alternator/alternator.md) and -[Getting started with Alternator](docs/alternator/getting-started.md). +[Alternator](docs/source/alternator/alternator.md) and +[Getting started with Alternator](docs/source/alternator/getting-started.md). ## Documentation -Documentation can be found [here](https://scylla.docs.scylladb.com). +Documentation can be found [here](docs/dev/README.md). Seastar documentation can be found [here](http://docs.seastar.io/master/index.html). User documentation can be found [here](https://docs.scylladb.com/). diff --git a/docs/Makefile b/docs/Makefile index 7c3d63a3aa..b3ba353c7f 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -1,19 +1,17 @@ +# Global variables # You can set these variables from the command line. -POETRY := poetry -SPHINXBUILD := $(POETRY) run sphinx-build -SPHINXOPTS := -PAPER := -BUILDDIR := _build -SOURCEDIR := . +POETRY = poetry +SPHINXOPTS = +SPHINXBUILD = $(POETRY) run sphinx-build +PAPER = +BUILDDIR = _build +SOURCEDIR = source -# Internal variables. -PAPEROPT_a4 := -D latex_paper_size=a4 -PAPEROPT_letter := -D latex_paper_size=letter -ALLSPHINXOPTS := -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) -TESTSPHINXOPTS := $(ALLSPHINXOPTS) -W --keep-going - -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS := $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) +# Internal variables +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) +TESTSPHINXOPTS = $(ALLSPHINXOPTS) -W --keep-going # Windows variables ifeq ($(OS),Windows_NT) @@ -69,7 +67,7 @@ epub3: setup .PHONY: multiversion multiversion: setup - $(POETRY) run sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/dirhtml + $(POETRY) run sphinx-multiversion source $(BUILDDIR)/dirhtml @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." @@ -91,4 +89,4 @@ test: setup .PHONY: linkcheck linkcheck: setup - $(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck + $(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index 7d5bfacb2a..0000000000 --- a/docs/README.md +++ /dev/null @@ -1,15 +0,0 @@ -# Scylla Developer Documentation - -This documentation targets developers who are interested in contributing to Scylla codebase. - -## Contents - -* [Alternator](alternator/alternator.md) - The open source DynamoDB-compatible API reference. -* [Design notes](design-notes/index.md) - Explanations describing how new features work for other contributors and exploratory research. -* [Guides](guides/index.md) - Instructions on how to build, run, test and debug the Scylla codebase. -* [Contribute](contribute/index.md) - Guidelines on how to contribute and maintain the project. - -## Other Useful Documents and Links - -* [User documentation](https://docs.scylladb.com/) -* [Seastar documentation](http://docs.seastar.io/master/index.html) diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 583ec30881..0000000000 --- a/docs/conf.py +++ /dev/null @@ -1,150 +0,0 @@ -# -*- coding: utf-8 -*- -import os -import sys -from datetime import date -import recommonmark -from recommonmark.transform import AutoStructify -from pygments.lexers.javascript import JavascriptLexer -from sphinx_scylladb_theme.utils import multiversion_regex_builder - -sys.path.insert(0, os.path.abspath('..')) - -# -- General configuration ------------------------------------------------ - -# Build documentation for the following tags and branches -TAGS = [] -BRANCHES = ['branch-4.5', 'branch-4.6', 'master'] -# Set the latest version. -LATEST_VERSION = 'branch-4.6' -# Set which versions are not released yet. -UNSTABLE_VERSIONS = ['master'] -# Set which versions are deprecated -DEPRECATED_VERSIONS = [''] - -# 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.mathjax', - 'sphinx.ext.githubpages', - 'sphinx.ext.extlinks', - 'sphinx_sitemap', - 'sphinx_scylladb_theme', - 'sphinx_multiversion', - 'recommonmark', - 'sphinx_markdown_tables', -] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# -source_suffix = ['.rst', '.md'] -autosectionlabel_prefix_document = True - -# The master toctree document. -master_doc = 'contents' - -# General information about the project. -project = 'Scylla Dev' -copyright = str(date.today().year) + ', ScyllaDB. All rights reserved.' -author = u'Scylla Project Contributors' - -# 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', 'README.md', '_utils'] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# -- Options for not found extension ------------------------------------------- - -# Template used to render the 404.html generated by this extension. -notfound_template = '404.html' - -# Prefix added to all the URLs generated in the 404 page. -notfound_urls_prefix = '' - -# -- Options for redirect extension --------------------------------------- - -# Read a YAML dictionary of redirections and generate an HTML file for each -redirects_file = '_utils/redirections.yaml' - -# -- Options for multiversion extension ---------------------------------- -# Whitelist pattern for tags -smv_tag_whitelist = multiversion_regex_builder(TAGS) -# Whitelist pattern for branches -smv_branch_whitelist = multiversion_regex_builder(BRANCHES) -# Defines which version is considered to be the latest stable version. -smv_latest_version = LATEST_VERSION -# Defines the new name for the latest version. -smv_rename_latest_version = 'stable' -# Whitelist pattern for remotes (set to None to use local branches only) -smv_remote_whitelist = r'^origin$' -# Pattern for released versions -smv_released_pattern = r'^tags/.*$' -# Format for versioned output directories inside the build directory -smv_outputdir_format = '{ref.name}' - -# -- Options for sitemap extension --------------------------------------- - -sitemap_url_scheme = 'stable/{link}' - -# -- 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_scylladb_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 = { - 'conf_py_path': 'docs/', - 'default_branch': 'master', - 'github_repository': 'scylladb/scylla', - 'github_issues_repository': 'scylladb/scylla', - 'hide_edit_this_page_button': 'false', - 'hide_version_dropdown': ['master'], - 'versions_unstable': UNSTABLE_VERSIONS, - 'versions_deprecated': DEPRECATED_VERSIONS, -} - -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -# -html_last_updated_fmt = '%d %B %Y' - -# Custom sidebar templates, maps document names to template names. -# -html_sidebars = {'**': ['side-nav.html']} - -# Output file base name for HTML help builder. -htmlhelp_basename = 'ScyllaDocumentationdoc' - -# URL which points to the root of the HTML documentation. -html_baseurl = 'https://scylla.docs.scylladb.com' - -# Dictionary of values to pass into the template engine’s context for all pages -html_context = {'html_baseurl': html_baseurl} - - -class AssemblyScriptLexer(JavascriptLexer): - pass - -# Setup Sphinx -def setup(sphinx): - # Add Markdown support - sphinx.add_config_value('recommonmark_config', { - 'enable_eval_rst': True, - 'enable_auto_toc_tree': False, - }, True) - sphinx.add_transform(AutoStructify) - - # Custom lexers - sphinx.add_lexer('assemblyscript', AssemblyScriptLexer) - diff --git a/docs/contents.rst b/docs/contents.rst deleted file mode 100644 index bd1ce13ea0..0000000000 --- a/docs/contents.rst +++ /dev/null @@ -1,9 +0,0 @@ -.. toctree:: - :hidden: - :maxdepth: 2 - - index - alternator/alternator - design-notes/index - guides/index - contribute/index diff --git a/docs/contribute/CONTRIBUTING.md b/docs/contribute/CONTRIBUTING.md deleted file mode 120000 index f939e75f21..0000000000 --- a/docs/contribute/CONTRIBUTING.md +++ /dev/null @@ -1 +0,0 @@ -../../CONTRIBUTING.md \ No newline at end of file diff --git a/docs/contribute/index.md b/docs/contribute/index.md deleted file mode 100644 index bb79ded012..0000000000 --- a/docs/contribute/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Contribute - -Guidelines on how to contribute and maintain the project. - -## Contents - -```eval_rst -.. toctree:: - :glob: - :maxdepth: 1 - - * -``` diff --git a/docs/design-notes/index.md b/docs/design-notes/index.md deleted file mode 100644 index 1abbec07ae..0000000000 --- a/docs/design-notes/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Design Notes - -Explanations describing how new features work for other contributors and exploratory research. - -## Contents - -```eval_rst -.. toctree:: - :glob: - :maxdepth: 1 - - * -``` diff --git a/docs/design-notes/IDL.md b/docs/dev/IDL.md similarity index 100% rename from docs/design-notes/IDL.md rename to docs/dev/IDL.md diff --git a/docs/dev/README.md b/docs/dev/README.md new file mode 100644 index 0000000000..ac29bb0733 --- /dev/null +++ b/docs/dev/README.md @@ -0,0 +1,16 @@ +# Scylla developer documentation + +This folder (and its subfolders) contain developer-oriented documentation +concerning the Scylla codebase. +We also have a [wiki](https://github.com/scylladb/scylla/wiki), which contains +additional developer-oriented documentation. There is currently no clear +definition of what goes where, so when looking for something be sure to check +both. + +Seastar documentation can be found [here](http://docs.seastar.io/master/index.html). + +User documentation can be found on +[docs.scylladb.com](https://docs.scylladb.com/) + +For information on how to build Scylla and how to contribute visit +[HACKING.md](../../HACKING.md) and [CONTRIBUTING.md](../../CONTRIBUTING.md). diff --git a/docs/guides/api_v2.md b/docs/dev/api_v2.md similarity index 100% rename from docs/guides/api_v2.md rename to docs/dev/api_v2.md diff --git a/docs/contribute/backport.md b/docs/dev/backport.md similarity index 100% rename from docs/contribute/backport.md rename to docs/dev/backport.md diff --git a/docs/guides/building.md b/docs/dev/building.md similarity index 100% rename from docs/guides/building.md rename to docs/dev/building.md diff --git a/docs/design-notes/cdc.md b/docs/dev/cdc.md similarity index 100% rename from docs/design-notes/cdc.md rename to docs/dev/cdc.md diff --git a/docs/design-notes/compaction_controller.md b/docs/dev/compaction_controller.md similarity index 100% rename from docs/design-notes/compaction_controller.md rename to docs/dev/compaction_controller.md diff --git a/docs/design-notes/cql-extensions-internal.md b/docs/dev/cql-extensions-internal.md similarity index 100% rename from docs/design-notes/cql-extensions-internal.md rename to docs/dev/cql-extensions-internal.md diff --git a/docs/design-notes/cql-extensions.md b/docs/dev/cql-extensions.md similarity index 100% rename from docs/design-notes/cql-extensions.md rename to docs/dev/cql-extensions.md diff --git a/docs/design-notes/cql3-type-mapping.md b/docs/dev/cql3-type-mapping.md similarity index 100% rename from docs/design-notes/cql3-type-mapping.md rename to docs/dev/cql3-type-mapping.md diff --git a/docs/guides/debugging.md b/docs/dev/debugging.md similarity index 100% rename from docs/guides/debugging.md rename to docs/dev/debugging.md diff --git a/docs/guides/docker-hub.md b/docs/dev/docker-hub.md similarity index 98% rename from docs/guides/docker-hub.md rename to docs/dev/docker-hub.md index 6794b9267f..926b061461 100644 --- a/docs/guides/docker-hub.md +++ b/docs/dev/docker-hub.md @@ -206,7 +206,7 @@ Note that the `--alternator-https-port` option also requires that files `/etc/sc #### `--alternator-write-isolation policy` -The `--alternator-write-isolation` command line option chooses between four allowed write isolation policies described in docs/alternator/alternator.md. This option must be specified if Alternator is enabled - it does not have a default. +The `--alternator-write-isolation` command line option chooses between four allowed write isolation policies described in docs/source/alternator/alternator.md. This option must be specified if Alternator is enabled - it does not have a default. **Since: 4.1** diff --git a/docs/design-notes/hinted_handoff_design.md b/docs/dev/hinted_handoff_design.md similarity index 100% rename from docs/design-notes/hinted_handoff_design.md rename to docs/dev/hinted_handoff_design.md diff --git a/docs/design-notes/isolation.md b/docs/dev/isolation.md similarity index 100% rename from docs/design-notes/isolation.md rename to docs/dev/isolation.md diff --git a/docs/guides/logging.md b/docs/dev/logging.md similarity index 100% rename from docs/guides/logging.md rename to docs/dev/logging.md diff --git a/docs/design-notes/lua-type-mapping.md b/docs/dev/lua-type-mapping.md similarity index 100% rename from docs/design-notes/lua-type-mapping.md rename to docs/dev/lua-type-mapping.md diff --git a/docs/contribute/maintainer.md b/docs/dev/maintainer.md similarity index 99% rename from docs/contribute/maintainer.md rename to docs/dev/maintainer.md index 14066697cc..905a2d982a 100644 --- a/docs/contribute/maintainer.md +++ b/docs/dev/maintainer.md @@ -268,7 +268,7 @@ still has to rely on their judgemenet. 2. Have a subject matter expert review the code. If you are not familiar with the modified code, ask one to do a review. For more details on how to review patches, see - the [review checklist](https://github.com/scylladb/scylla/blob/master/docs/contribute/review-checklist.md). + the [review checklist](review-checklist.md). 3. If the pull request fixes an issue, it should have a Fixes or Refs depending on whether the fix is complete or diff --git a/docs/design-notes/metrics.md b/docs/dev/metrics.md similarity index 100% rename from docs/design-notes/metrics.md rename to docs/dev/metrics.md diff --git a/docs/design-notes/migrating-from-users-to-roles.md b/docs/dev/migrating-from-users-to-roles.md similarity index 100% rename from docs/design-notes/migrating-from-users-to-roles.md rename to docs/dev/migrating-from-users-to-roles.md diff --git a/docs/design-notes/paged-queries.md b/docs/dev/paged-queries.md similarity index 100% rename from docs/design-notes/paged-queries.md rename to docs/dev/paged-queries.md diff --git a/docs/design-notes/parallel_aggregations.md b/docs/dev/parallel_aggregations.md similarity index 100% rename from docs/design-notes/parallel_aggregations.md rename to docs/dev/parallel_aggregations.md diff --git a/docs/design-notes/per-partition-rate-limit.md b/docs/dev/per-partition-rate-limit.md similarity index 100% rename from docs/design-notes/per-partition-rate-limit.md rename to docs/dev/per-partition-rate-limit.md diff --git a/docs/design-notes/protocol-extensions.md b/docs/dev/protocol-extensions.md similarity index 100% rename from docs/design-notes/protocol-extensions.md rename to docs/dev/protocol-extensions.md diff --git a/docs/design-notes/protocols.md b/docs/dev/protocols.md similarity index 99% rename from docs/design-notes/protocols.md rename to docs/dev/protocols.md index 94a9955553..2cd6bbcfd5 100644 --- a/docs/design-notes/protocols.md +++ b/docs/dev/protocols.md @@ -197,7 +197,7 @@ HTTP (unencrypted) or HTTPS (encrypted) protocol. Support for this protocol is not turned on by default, and must be turned on manually by setting the `alternator_port` and/or `alternator_https_port` configuration options. "Alternator" is the codename of Scylla's DynamoDB API support, and is -documented in more detail in [alternator.md](../alternator/alternator.md). +documented in more detail in [alternator.md](../source/alternator/alternator.md). The standard ports that DynamoDB uses are the standard HTTP and HTTPS ports (80 and 443, respectively), but in tests we usually use the diff --git a/docs/design-notes/raft-in-scylla.md b/docs/dev/raft-in-scylla.md similarity index 100% rename from docs/design-notes/raft-in-scylla.md rename to docs/dev/raft-in-scylla.md diff --git a/docs/design-notes/redis.md b/docs/dev/redis.md similarity index 100% rename from docs/design-notes/redis.md rename to docs/dev/redis.md diff --git a/docs/design-notes/repair_based_node_ops.md b/docs/dev/repair_based_node_ops.md similarity index 100% rename from docs/design-notes/repair_based_node_ops.md rename to docs/dev/repair_based_node_ops.md diff --git a/docs/design-notes/reverse-reads.md b/docs/dev/reverse-reads.md similarity index 100% rename from docs/design-notes/reverse-reads.md rename to docs/dev/reverse-reads.md diff --git a/docs/contribute/review-checklist.md b/docs/dev/review-checklist.md similarity index 100% rename from docs/contribute/review-checklist.md rename to docs/dev/review-checklist.md diff --git a/docs/design-notes/row_cache.md b/docs/dev/row_cache.md similarity index 100% rename from docs/design-notes/row_cache.md rename to docs/dev/row_cache.md diff --git a/docs/design-notes/row_level_repair.md b/docs/dev/row_level_repair.md similarity index 100% rename from docs/design-notes/row_level_repair.md rename to docs/dev/row_level_repair.md diff --git a/docs/design-notes/rust.md b/docs/dev/rust.md similarity index 100% rename from docs/design-notes/rust.md rename to docs/dev/rust.md diff --git a/docs/design-notes/secondary_index.md b/docs/dev/secondary_index.md similarity index 100% rename from docs/design-notes/secondary_index.md rename to docs/dev/secondary_index.md diff --git a/docs/design-notes/service_levels.md b/docs/dev/service_levels.md similarity index 100% rename from docs/design-notes/service_levels.md rename to docs/dev/service_levels.md diff --git a/docs/design-notes/sstable-scylla-format.md b/docs/dev/sstable-scylla-format.md similarity index 100% rename from docs/design-notes/sstable-scylla-format.md rename to docs/dev/sstable-scylla-format.md diff --git a/docs/design-notes/sstables-directory-structure.md b/docs/dev/sstables-directory-structure.md similarity index 100% rename from docs/design-notes/sstables-directory-structure.md rename to docs/dev/sstables-directory-structure.md diff --git a/docs/design-notes/system_keyspace.md b/docs/dev/system_keyspace.md similarity index 99% rename from docs/design-notes/system_keyspace.md rename to docs/dev/system_keyspace.md index ac19ae8b8e..45f3fe53be 100644 --- a/docs/design-notes/system_keyspace.md +++ b/docs/dev/system_keyspace.md @@ -153,7 +153,7 @@ legacy records. When the feature is agreed upon the legacy map is removed. Virtual tables behave just like a regular table from the user's point of view. The difference between them and regular tables comes down to how they are implemented. While regular tables have memtables/commitlog/sstables and all you would expect from CQL tables, virtual tables translate some in-memory structure to CQL result format. -For more details see the [docs/guides/virtual-tables.md](../guides/virtual-tables.md). +For more details see the [virtual-tables.md](virtual-tables.md). Below you can find a list of virtual tables. Sorted in alphabetical order (please keep it so when modifying!). diff --git a/docs/design-notes/system_schema_keyspace.md b/docs/dev/system_schema_keyspace.md similarity index 100% rename from docs/design-notes/system_schema_keyspace.md rename to docs/dev/system_schema_keyspace.md diff --git a/docs/guides/testing.md b/docs/dev/testing.md similarity index 100% rename from docs/guides/testing.md rename to docs/dev/testing.md diff --git a/docs/guides/tracing.md b/docs/dev/tracing.md similarity index 100% rename from docs/guides/tracing.md rename to docs/dev/tracing.md diff --git a/docs/guides/virtual-tables.md b/docs/dev/virtual-tables.md similarity index 100% rename from docs/guides/virtual-tables.md rename to docs/dev/virtual-tables.md diff --git a/docs/design-notes/wasm.md b/docs/dev/wasm.md similarity index 100% rename from docs/design-notes/wasm.md rename to docs/dev/wasm.md diff --git a/docs/guides/index.md b/docs/guides/index.md deleted file mode 100644 index 6f89a9692c..0000000000 --- a/docs/guides/index.md +++ /dev/null @@ -1,13 +0,0 @@ -# Guides - -Instructions on how to build and test the Scylla codebase. - -## Contents - -```eval_rst -.. toctree:: - :glob: - :maxdepth: 1 - - * -``` diff --git a/docs/index.md b/docs/index.md deleted file mode 120000 index 42061c01a1..0000000000 --- a/docs/index.md +++ /dev/null @@ -1 +0,0 @@ -README.md \ No newline at end of file diff --git a/docs/alternator/alternator.md b/docs/source/alternator/alternator.md similarity index 100% rename from docs/alternator/alternator.md rename to docs/source/alternator/alternator.md diff --git a/docs/alternator/compatibility.md b/docs/source/alternator/compatibility.md similarity index 100% rename from docs/alternator/compatibility.md rename to docs/source/alternator/compatibility.md diff --git a/docs/alternator/getting-started.md b/docs/source/alternator/getting-started.md similarity index 100% rename from docs/alternator/getting-started.md rename to docs/source/alternator/getting-started.md diff --git a/docs/source/conf.py b/docs/source/conf.py new file mode 100644 index 0000000000..326525d947 --- /dev/null +++ b/docs/source/conf.py @@ -0,0 +1,141 @@ +# -*- coding: utf-8 -*- +import os +import sys +import warnings +from datetime import date + +from sphinx_scylladb_theme.utils import multiversion_regex_builder +from recommonmark.transform import AutoStructify + +sys.path.insert(0, os.path.abspath("..")) + +# -- Global variables + +# Build documentation for the following tags and branches +TAGS = [] +BRANCHES = [] +# Set the latest version. +LATEST_VERSION = "branch-1.2" +# Set which versions are not released yet. +UNSTABLE_VERSIONS = ["master"] +# Set which versions are deprecated +DEPRECATED_VERSIONS = [""] + +# -- General configuration ------------------------------------------------ + +# Add any Sphinx extension module names here, as strings. +extensions = [ + "sphinx.ext.autodoc", + "sphinx.ext.todo", + "sphinx.ext.mathjax", + "sphinx.ext.githubpages", + "sphinx.ext.extlinks", + "sphinx_sitemap", + "sphinx_scylladb_theme", + "sphinx_multiversion", # optional + "recommonmark", # optional +] + +# The suffix(es) of source filenames. +source_suffix = [".rst", ".md"] + +# The master toctree document. +master_doc = "index" + +# General information about the project. +project = "ScyllaDB Documentation" +copyright = str(date.today().year) + ", ScyllaDB. All rights reserved." +author = u"Scylla Project Contributors" + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = "sphinx" + +# List of substitutions +rst_prolog = """ +.. |rst| replace:: restructuredText +""" +# -- Options for not found extension --------------------------------------- + +# Template used to render the 404.html generated by this extension. +notfound_template = "404.html" + +# Prefix added to all the URLs generated in the 404 page. +notfound_urls_prefix = "" + +# -- Options for sitemap extension --------------------------------------- + +sitemap_url_scheme = "stable/{link}" + +# -- Options for redirect extension -------------------------------------- + +# Read a YAML dictionary of redirections and generate an HTML file for each +redirects_file = "_utils/redirections.yaml" + +# -- Options for multiversion extension ---------------------------------- + +# Whitelist pattern for tags +smv_tag_whitelist = multiversion_regex_builder(TAGS) +# Whitelist pattern for branches +smv_branch_whitelist = multiversion_regex_builder(BRANCHES) +# Defines which version is considered to be the latest stable version. +smv_latest_version = LATEST_VERSION +# Defines the new name for the latest version. +smv_rename_latest_version = "stable" +# Whitelist pattern for remotes (set to None to use local branches only) +smv_remote_whitelist = r"^origin$" +# Pattern for released versions +smv_released_pattern = r"^tags/.*$" +# Format for versioned output directories inside the build directory +smv_outputdir_format = "{ref.name}" + +# -- Options for HTML output ---------------------------------------------- + +# The theme to use for pages. +html_theme = "sphinx_scylladb_theme" +html_theme_path = ["../.."] + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for the theme, see the +# documentation. +html_theme_options = { + "conf_py_path": "docs/source/", + "hide_edit_this_page_button": "false", + "hide_banner": "false", + "github_issues_repository": "scylladb/scylla", + "github_repository": "scylladb/scylla", + "hide_version_dropdown": ["master"], + "versions_unstable": UNSTABLE_VERSIONS, + "versions_deprecated": DEPRECATED_VERSIONS, +} + +# Last updated format +html_last_updated_fmt = "%d %b %Y" + +# Custom sidebar templates, maps document names to template names. +html_sidebars = {"**": ["side-nav.html"]} + +# Output file base name for HTML help builder. +htmlhelp_basename = "ScyllaDocumentationdoc" + +# URL which points to the root of the HTML documentation. +html_baseurl = "https://sphinx-theme.scylladb.com" + +# Dictionary of values to pass into the template engine’s context for all pages +html_context = {"html_baseurl": html_baseurl} + + +# -- Initialize Sphinx ---------------------------------------------- +def setup(sphinx): + warnings.filterwarnings( + action="ignore", + category=UserWarning, + message=r".*Container node skipped.*", + ) + sphinx.add_config_value('recommonmark_config', { + 'enable_eval_rst': True, + }, True) + sphinx.add_transform(AutoStructify) diff --git a/docs/source/index.rst b/docs/source/index.rst new file mode 100644 index 0000000000..e63af33cff --- /dev/null +++ b/docs/source/index.rst @@ -0,0 +1,8 @@ +Welcome to ScyllaDB Documentation +================================= + +.. toctree:: + :glob: + :maxdepth: 1 + + alternator/alternator diff --git a/gdbinit b/gdbinit index 18e22891b9..52ee86b9b8 100644 --- a/gdbinit +++ b/gdbinit @@ -1,5 +1,5 @@ # Recommended .gdbinit for debugging scylla -# See docs/guides/debugging.md for more information +# See docs/dev/debugging.md for more information handle SIG34 pass noprint handle SIGUSR1 pass noprint set print pretty diff --git a/idl/read_command.idl.hh b/idl/read_command.idl.hh index ae0c338c42..0241b7d021 100644 --- a/idl/read_command.idl.hh +++ b/idl/read_command.idl.hh @@ -21,7 +21,7 @@ class specific_ranges { // format: // * legacy format // * native format -// The wire format uses the legacy format. See docs/design-notes/reverse-reads.md +// The wire format uses the legacy format. See docs/dev/reverse-reads.md // for more details on the formats. class partition_slice { std::vector> default_row_ranges(); diff --git a/query-request.hh b/query-request.hh index 767a1c7c42..afbf3c07e9 100644 --- a/query-request.hh +++ b/query-request.hh @@ -139,7 +139,7 @@ constexpr auto max_rows_if_set = std::numeric_limits::max(); // format: // * legacy format // * native format -// The wire format uses the legacy format. See docs/design-notes/reverse-reads.md +// The wire format uses the legacy format. See docs/dev/reverse-reads.md // for more details on the formats. class partition_slice { friend class ::partition_slice_builder; @@ -249,7 +249,7 @@ public: friend std::ostream& operator<<(std::ostream& out, const specific_ranges& ps); }; -// See docs/design-notes/reverse-reads.md +// See docs/dev/reverse-reads.md // In the following functions, `schema` may be reversed or not (both work). partition_slice legacy_reverse_slice_to_native_reverse_slice(const schema& schema, partition_slice slice); partition_slice native_reverse_slice_to_legacy_reverse_slice(const schema& schema, partition_slice slice); diff --git a/range_tombstone.hh b/range_tombstone.hh index bcd4477575..a1c0fb5e62 100644 --- a/range_tombstone.hh +++ b/range_tombstone.hh @@ -180,7 +180,7 @@ public: } // Swap bounds to reverse range-tombstone -- as if it came from a table with - // reverse native order. See docs/design-notes/reverse-reads.md. + // reverse native order. See docs/dev/reverse-reads.md. void reverse() { std::swap(start, end); std::swap(start_kind, end_kind); diff --git a/readers/mutation_source.hh b/readers/mutation_source.hh index f2d187acc5..e309694f36 100644 --- a/readers/mutation_source.hh +++ b/readers/mutation_source.hh @@ -38,7 +38,7 @@ partition_presence_checker make_default_partition_presence_checker() { // // When reading in reverse, a reverse schema has to be passed (compared to the // table's schema), and a half-reverse (legacy) slice. -// See docs/design-notes/reverse-reads.md for more details. +// See docs/dev/reverse-reads.md for more details. // Partition-range forwarding is not yet supported in reverse mode. class mutation_source { using partition_range = const dht::partition_range&; diff --git a/readers/reversing_v2.hh b/readers/reversing_v2.hh index 075402bcfe..2c89a92f94 100644 --- a/readers/reversing_v2.hh +++ b/readers/reversing_v2.hh @@ -27,7 +27,7 @@ namespace query { /// account for the implicit null tombstone at the start of the stream moving /// from start to end (due to reversing). /// Ordering of partitions themselves remains unchanged. -/// For more details see docs/design-notes/reverse-reads.md. +/// For more details see docs/dev/reverse-reads.md. /// /// The reader's schema (returned by `schema()`) is the reverse of `original`'s schema. /// diff --git a/sstables/sstable_set.cc b/sstables/sstable_set.cc index 102040d5a3..7d832ad6ea 100644 --- a/sstables/sstable_set.cc +++ b/sstables/sstable_set.cc @@ -488,7 +488,7 @@ class sstable_position_reader_queue : public position_reader_queue { public: // Assumes that `create_reader` returns readers that emit only fragments from partition `pk`. // - // For reversed reads `query_schema` must be reversed (see docs/design-notes/reverse-reads.md). + // For reversed reads `query_schema` must be reversed (see docs/dev/reverse-reads.md). sstable_position_reader_queue(const time_series_sstable_set& set, schema_ptr query_schema, std::function create_reader, diff --git a/test/alternator/test_metrics.py b/test/alternator/test_metrics.py index 81372489e6..21ba1ec529 100644 --- a/test/alternator/test_metrics.py +++ b/test/alternator/test_metrics.py @@ -3,7 +3,7 @@ # SPDX-License-Identifier: AGPL-3.0-or-later ############################################################################## -# Tests for Scylla's metrics (see docs/design-notes/metrics.md) for Alternator +# Tests for Scylla's metrics (see docs/dev/metrics.md) for Alternator # queries. Reproduces issue #9406, where although metrics was implemented for # Alternator requests, they were missing for some operations (BatchGetItem). # In the tests here we attempt to ensure that the metrics continue to work diff --git a/tools/scylla-types.cc b/tools/scylla-types.cc index f22da9a2ec..58da2465bb 100644 --- a/tools/scylla-types.cc +++ b/tools/scylla-types.cc @@ -204,7 +204,7 @@ without a leading 0x prefix, e.g. 00783562. For scylla-types to be able to examine the values, their type has to be provided. Types should be provided by their cassandra class names, e.g. org.apache.cassandra.db.marshal.Int32Type for the int32_type. The org.apache.cassandra.db.marshal. prefix can be ommited. -See https://github.com/scylladb/scylla/blob/master/docs/design-notes/cql3-type-mapping.md +See https://github.com/scylladb/scylla/blob/master/docs/dev/cql3-type-mapping.md for a mapping of cql3 types to Cassandra type class names. Compound types specify their subtypes inside () separated by comma, e.g.: MapType(Int32Type, BytesType). All provided values have to share the same type.