114 lines
3.0 KiB
Markdown
114 lines
3.0 KiB
Markdown
# Scylla documentation
|
|
|
|
This is the repository for [Scylla documentation site](http://docs.scylladb.com/)
|
|
|
|
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](https://docs.errata.ai/vale/install) for your operative system.
|
|
|
|
### Prerequisites: Mac OS X
|
|
|
|
You must have a working [Homebrew](http://brew.sh/) 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
|
|
|
|
```sh
|
|
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:
|
|
|
|
```sh
|
|
make proofread
|
|
```
|
|
|
|
Lint one file (e.g. README.md):
|
|
|
|
```sh
|
|
make proofread path=README.md
|
|
```
|
|
|
|
Lint one folder (e.g. getting-started):
|
|
|
|
```sh
|
|
make proofread path=getting-started
|
|
```
|
|
|
|
# Cleanup
|
|
|
|
You can clean up all the build products and auto-installed Python stuff with:
|
|
|
|
```sh
|
|
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.
|
|
* Run`make 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.
|
|
```
|