Skip to content

Commit 4337888

Browse files
darwin67darwin67
committed
docs: restore inherited docs references
1 parent 310b034 commit 4337888

612 files changed

Lines changed: 53998 additions & 6 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/.gitignore‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
_build
2+
poetry.lock
3+
_data

‎docs/Makefile‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# Global variables
2+
# You can set these variables from the command line.
3+
POETRY := poetry
4+
SPHINXOPTS := -j auto
5+
SPHINXBUILD := $(POETRY) run sphinx-build
6+
PAPER :=
7+
BUILDDIR := _build
8+
SOURCEDIR := .
9+
PREVIEW_HOST := 127.0.0.1
10+
FLAG := opensource
11+
CONF_PATH := ./
12+
13+
# Internal variables
14+
ifeq ($(FLAG), enterprise)
15+
CONF_PATH = ./_enterprise
16+
endif
17+
18+
PAPEROPT_a4 := -D latex_paper_size=a4
19+
PAPEROPT_letter := -D latex_paper_size=letter
20+
ALLSPHINXOPTS := -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SOURCEDIR) -t $(FLAG) -c $(CONF_PATH)
21+
TESTSPHINXOPTS := $(ALLSPHINXOPTS) -W --keep-going
22+
PROD_OPTS := -D html_theme_options.collapse_navigation='false' -D html_theme_options.navigation_depth=3 -t $(FLAG) -c $(CONF_PATH)
23+
24+
.PHONY: all
25+
all: dirhtml
26+
27+
# Setup commands
28+
.PHONY: setupenv
29+
setupenv:
30+
pip install -q 'poetry>=1.8.0'
31+
32+
.PHONY: setup
33+
setup:
34+
$(POETRY) install
35+
$(POETRY) update
36+
37+
# Clean commands
38+
.PHONY: pristine
39+
pristine: clean
40+
git clean -dfX
41+
42+
.PHONY: clean
43+
clean:
44+
rm -rf $(BUILDDIR)/*
45+
rm -rf _data/*
46+
rm -f poetry.lock
47+
48+
# Generate output commands
49+
.PHONY: dirhtml
50+
dirhtml: setup
51+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
52+
@echo
53+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
54+
55+
.PHONY: singlehtml
56+
singlehtml: setup
57+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
58+
@echo
59+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
60+
61+
.PHONY: epub
62+
epub: setup
63+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
64+
@echo
65+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
66+
67+
.PHONY: epub3
68+
epub3: setup
69+
$(SPHINXBUILD) -b epub3 $(ALLSPHINXOPTS) $(BUILDDIR)/epub3
70+
@echo
71+
@echo "Build finished. The epub3 file is in $(BUILDDIR)/epub3."
72+
73+
.PHONY: multiversion
74+
multiversion: setup
75+
$(POETRY) run sphinx-multiversion $(SOURCEDIR) $(BUILDDIR)/dirhtml $(PROD_OPTS)
76+
@echo
77+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
78+
79+
.PHONY: redirects
80+
redirects: setup
81+
$(POETRY) run redirects-cli fromfile --yaml-file ./_utils/redirects.yaml --output-dir $(BUILDDIR)/dirhtml
82+
@echo
83+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
84+
85+
# Preview commands
86+
.PHONY: preview
87+
preview: setup
88+
$(POETRY) run sphinx-autobuild -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml --host $(PREVIEW_HOST) --port 5500 --ignore *.csv --ignore *.json --ignore *.yaml
89+
90+
.PHONY: multiversionpreview
91+
multiversionpreview: multiversion
92+
$(POETRY) run python -m http.server 5500 --directory $(BUILDDIR)/dirhtml
93+
94+
# Test commands
95+
.PHONY: test
96+
test: setup
97+
$(SPHINXBUILD) -b dirhtml $(TESTSPHINXOPTS) $(BUILDDIR)/dirhtml
98+
@echo
99+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
100+
101+
.PHONY: linkcheck
102+
linkcheck: setup
103+
$(SPHINXBUILD) -b linkcheck $(SOURCEDIR) $(BUILDDIR)/linkcheck
104+

‎docs/README.md‎

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# ScyllaDB Documentation
2+
3+
This repository contains the source files for ScyllaDB Open Source documentation.
4+
5+
- The `dev` folder contains developer-oriented documentation related to the ScyllaDB code base. It is not published and is only available via GitHub.
6+
- All other folders and files contain user-oriented documentation related to ScyllaDB Open Source and are sources for [docs.scylladb.com](https://docs.scylladb.com/).
7+
8+
To report a documentation bug or suggest an improvement, open an issue in [GitHub issues](https://github.com/scylladb/scylla/issues) for this project.
9+
10+
To contribute to the documentation, open a GitHub pull request.
11+
12+
## Key Guidelines for Contributors
13+
14+
- Follow the [ScyllaDB Style Guide](https://docs.google.com/document/d/1lyHp1MKdyj0Hh3NprNFvEczA4dFSZIFoukGUvFJb9yE/edit?usp=sharing).
15+
- The user documentation is written in reStructuredText (RST) - a plaintext markup language similar to Markdown. If you're not familiar with RST, see [ScyllaDB RST Examples](https://sphinx-theme.scylladb.com/stable/examples/index.html).
16+
- The developer documentation is written in Markdown. See [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) for reference.
17+
18+
19+
## Creating Knowledge Base Articles
20+
21+
The `kb/` directory holds source files for knowledge base articles in the [Knowledge Base section](https://docs.scylladb.com/stable/kb/index.html) of the ScyllaDB documentation.
22+
23+
The `kb/kb_common` subdirectory contains a template for knowledge base articles to help you create new articles.
24+
25+
To create a new knowledge base article (KB):
26+
27+
1. Copy the `kb-article-template.rst` file from `/kb/kb_common` to `/kb` and rename it with a unique name.
28+
1. Open the new file and fill in the required information.
29+
1. Remove what is not needed.
30+
1. Run `make preview` to build the docs and preview them locally.
31+
1. Send a PR with "KB" in its title.
32+
33+
34+
## Building User Documentation
35+
36+
### Prerequisites
37+
38+
* Python 3. Check your version with `$ python --version`.
39+
* [poetry](https://python-poetry.org/) 1.12 or later
40+
* make
41+
42+
#### Mac OS X
43+
44+
You must have a working [Homebrew](http://brew.sh/) in order to install the needed tools.
45+
46+
You also need the standard utility `make`.
47+
48+
Check if you have these two items with the following commands:
49+
50+
```sh
51+
brew help
52+
make -h
53+
```
54+
55+
#### Linux Distributions
56+
57+
Building the user docs should work out of the box on most Linux distributions.
58+
59+
#### Windows
60+
61+
Use "Bash on Ubuntu on Windows" for the same tools and capabilities as on Linux distributions.
62+
63+
### Building the Docs
64+
65+
1. Run `make preview` to build the documentation.
66+
1. Preview the built documentation locally at http://127.0.0.1:5500/.
67+
68+
### Cleanup
69+
70+
You can clean up all the build products and auto-installed Python stuff with:
71+
72+
```sh
73+
make pristine
74+
```
75+
76+
## Information for Contributors
77+
78+
If you are interested in contributing to Scylla
79+
docs, please read the Scylla open source page at
80+
http://www.scylladb.com/opensource/ and complete
81+
a Scylla contributor agreement if needed. We can
82+
only accept documentation pull requests if we have
83+
a contributor agreement on file for you.
84+
85+
86+
## Third-party Documentation
87+
88+
* Do any copying as a separate commit. Always commit an unmodified version first and then do any editing in a separate commit.
89+
90+
* We already have a copy of the Apache license in our tree, so you do not need to commit a copy of the license.
91+
92+
* Include the copyright header from the source file in the edited version. If you are copying an Apache Cassandra document with no copyright header, use:
93+
94+
```
95+
This document includes material from Apache Cassandra.
96+
Apache Cassandra is Copyright 2009-2014 The Apache Software Foundation.
97+
```

‎docs/_ext/__init__.py‎

Whitespace-only changes.

‎docs/_ext/scylladb_aws_images.py‎

Lines changed: 107 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,107 @@
1+
import csv
2+
import os
3+
import re
4+
5+
from sphinx.application import Sphinx
6+
from sphinx.util import logging
7+
from scylladb_common_images import FileDownloader, BaseVersionsTemplateDirective
8+
9+
LOGGER = logging.getLogger(__name__)
10+
11+
class CloudFormationProcessor:
12+
FILENAME_REGEX = r"^.+_(\d+\.\d+\.\d+)_(\w+)(\.yaml)?$"
13+
14+
def _extract_version_architecture(self, filename):
15+
match = re.match(self.FILENAME_REGEX, filename)
16+
if match:
17+
return match.groups()[:-1]
18+
return None, None
19+
20+
@staticmethod
21+
def _append_to_csv(csv_path, link, architecture):
22+
with open(csv_path, mode="r") as file:
23+
data = list(csv.reader(file))
24+
25+
header = data[0]
26+
col_name = f"Cluster_{architecture}"
27+
if col_name not in header:
28+
header.append(col_name)
29+
30+
for row in data[1:]:
31+
row.append(link)
32+
33+
with open(csv_path, mode="w", newline="") as file:
34+
writer = csv.writer(file)
35+
writer.writerows(data)
36+
37+
def process_files(self, download_directory, links):
38+
for link in reversed(links):
39+
version, architecture = self._extract_version_architecture(link)
40+
if version and architecture:
41+
matching_csv = next(
42+
(f for f in os.listdir(download_directory) if version in f), None
43+
)
44+
45+
if matching_csv:
46+
csv_path = os.path.join(download_directory, matching_csv)
47+
self._append_to_csv(csv_path, link, architecture)
48+
LOGGER.info("Appended cloudformation information to AWS images CSVs.")
49+
50+
51+
class AMIInformationDownloader:
52+
53+
def run(self, app, exception=None):
54+
config = app.config
55+
base_url = config.scylladb_aws_images_base_url
56+
bucket_directory = config.scylladb_aws_images_ami_bucket_directory
57+
download_directory = os.path.join(app.builder.srcdir, config.scylladb_aws_images_ami_download_directory)
58+
cloudformation_bucket_directory = config.scylladb_aws_images_cloudformation_bucket_directory
59+
60+
if os.path.exists(download_directory) and os.listdir(download_directory):
61+
LOGGER.info(f"Files already exist in {download_directory}. Skipping download.")
62+
63+
else:
64+
downloader = FileDownloader(base_url)
65+
downloader.download_files(bucket_directory, download_directory)
66+
processor = CloudFormationProcessor()
67+
links = downloader.get_links(cloudformation_bucket_directory, "yaml")
68+
processor.process_files(download_directory, links)
69+
70+
71+
class AMIVersionsTemplateDirective(BaseVersionsTemplateDirective):
72+
FILENAME_REGEX = re.compile(r"ami_ids_(\d+(?:\.\d+)?(?:\.\d+)?)(?:.*?)\.csv")
73+
TEMPLATE = 'aws_image.tmpl'
74+
75+
def get_download_directory(self, app):
76+
return os.path.join(app.builder.srcdir, app.config.scylladb_aws_images_ami_download_directory)
77+
78+
def setup(app: Sphinx):
79+
app.add_config_value(
80+
"scylladb_aws_images_base_url",
81+
default="https://s3.amazonaws.com/downloads.scylladb.com",
82+
rebuild="html",
83+
)
84+
app.add_config_value(
85+
"scylladb_aws_images_ami_bucket_directory",
86+
default="downloads/scylla/aws/ami/",
87+
rebuild="html",
88+
)
89+
app.add_config_value(
90+
"scylladb_aws_images_ami_download_directory",
91+
default="_data/opensource/aws/ami",
92+
rebuild="html",
93+
)
94+
app.add_config_value(
95+
"scylladb_aws_images_cloudformation_bucket_directory",
96+
default="downloads/scylla/aws/cloudformation/",
97+
rebuild="html",
98+
)
99+
app.connect("builder-inited", AMIInformationDownloader().run)
100+
101+
app.add_directive("scylladb_aws_images_template", AMIVersionsTemplateDirective)
102+
103+
return {
104+
"version": "0.1",
105+
"parallel_read_safe": True,
106+
"parallel_write_safe": True,
107+
}

‎docs/_ext/scylladb_azure_images.py‎

Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
import os
2+
import re
3+
4+
from sphinx.application import Sphinx
5+
from sphinx.util import logging
6+
from scylladb_common_images import FileDownloader, BaseVersionsTemplateDirective
7+
8+
LOGGER = logging.getLogger(__name__)
9+
10+
class AzureImagesInformationDownloader:
11+
12+
def run(self, app, exception=None):
13+
config = app.config
14+
base_url = config.scylladb_azure_images_base_url
15+
bucket_directory = config.scylladb_azure_images_ami_bucket_directory
16+
download_directory = os.path.join(app.builder.srcdir, config.scylladb_azure_images_download_directory)
17+
if os.path.exists(download_directory) and os.listdir(download_directory):
18+
LOGGER.info(f"Files already exist in {download_directory}. Skipping download.")
19+
else:
20+
downloader = FileDownloader(base_url)
21+
downloader.download_files(bucket_directory, download_directory)
22+
23+
class AzureImagesVersionsTemplateDirective(BaseVersionsTemplateDirective):
24+
FILENAME_REGEX = re.compile(r"azure_image_ids_(\d+(?:\.\d+)?(?:\.\d+)?)(?:.*?)\.csv")
25+
TEMPLATE = "azure_image.tmpl"
26+
27+
def get_download_directory(self, app):
28+
return os.path.join(app.builder.srcdir, app.config.scylladb_azure_images_download_directory)
29+
30+
def setup(app: Sphinx):
31+
app.add_config_value(
32+
"scylladb_azure_images_base_url",
33+
default="https://s3.amazonaws.com/downloads.scylladb.com",
34+
rebuild="html",
35+
)
36+
app.add_config_value(
37+
"scylladb_azure_images_ami_bucket_directory",
38+
default="downloads/scylla/azure/",
39+
rebuild="html",
40+
)
41+
app.add_config_value(
42+
"scylladb_azure_images_download_directory",
43+
default="_data/opensource/azure",
44+
rebuild="html",
45+
)
46+
app.connect("builder-inited", AzureImagesInformationDownloader().run)
47+
48+
app.add_directive("scylladb_azure_images_template", AzureImagesVersionsTemplateDirective)
49+
50+
return {
51+
"version": "0.1",
52+
"parallel_read_safe": True,
53+
"parallel_write_safe": True,
54+
}

0 commit comments

Comments
 (0)