scylladb/docs

Scylla documentation

This is the repository for Scylla documentation site

To report an issue with the documentation, please use GitHub issues.

This repository accepts GitHub pull requests.

Send pull requests to the master branch, not gh-pages. gh-pages will be overwritten by deploy without warning.

Prerequisites

• Python 3. Check your version with $ python --version
• Vale CLI (optional to lint docs). Install Vale for your operative system.

Prerequisites: Mac OS X

You must have a working Homebrew in order to install the needed tools.

You also need the standard utility make. (I don't know if this comes with Mac OS X.)

Check if you have these two items with

brew help
make -h

Prerequisites: Fedora 29/Debian-based Linux Distributions

This should work out of the box with Fedora 29.

Prerequisites: Windows

Use "Bash on Ubuntu on Windows", everything should be same as on a debian-based Linux. Note: livereload seems not working on Windows.

Prerequisites: other systems

FIXME

Working on the docs

Work on a task branch and send pull requests for master. Master is the default branch.

Run make preview to make the docs and preview locally.

Deploy

If you have the rights to push to the live site, run make deploy to deploy.

Lint

Lint all:

make proofread

Lint one file (e.g. README.md):

make proofread path=README.md

Lint one folder (e.g. getting-started):

make proofread path=getting-started

Cleanup

You can clean up all the build products and auto-installed Python stuff with:

make pristine

Contributor info

If you are interested in contributing to Scylla docs, please read the Scylla open source page at http://www.scylladb.com/opensource/ and complete a Scylla contributor agreement if needed. We can only accept documentation pull requests if we have a contributor agreement on file for you

Submitting a KB Article

If you are submitting a Knowledgebase Article (KBA), use the following guidelines:

• In the /kb_common directory there is a template for KBAs. It is called kb-article-template.rst.
• Make a copy of this file in the /kb directory, saving it with a unique name.
• Open the template and fill in the required inforation.
• Remove what is not needed.
• Runmake preview to make the docs and preview locally.
• Send a PR - add KBA in the title.

Third-party documentation

• Do any copying as a separate commit. Always commit an unmodified version first and then do any editing in a separate commit.

• We already have a copy of the Apache license in our tree so you do not need to commit a copy of the license.

• 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:

This document includes material from Apache Cassandra.
Apache Cassandra is Copyright 2009-2014 The Apache Software Foundation.