mirrors/scylladb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc: reogrganize the content in the doc's README

Browse Source
This commit is contained in:
Anna Stuchlik
2022-07-27 10:18:01 +02:00
parent e989eed75b
commit d4bc030705
1 changed files with 34 additions and 25 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
docs/README.md
View File

@@ -14,7 +14,6 @@ To contribute to the documentation, open a GitHub pull request.
- You need to fork this repository.
- Work on your fork's task branches, not the `master` branch.
- Send pull requests to the `master` branch in this repository.
- Run `make preview` to build the documentation and preview it locally at http://127.0.0.1:5500/.
- If you want to submit a knowledge base article, see [Submitting a KB Article](#submitting-a-kb-article).
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).
@@ -22,12 +21,25 @@ The user documentation is written in reStructuredText (RST) - a plaintext markup
The developer documentation is written in Markdown. See [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) for reference.
## Prerequisites for Building User Documentation
## 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.
## Building User Documentation
### 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.
### Mac OS X
#### Mac OS X
You must have a working [Homebrew](http://brew.sh/) in order to install the needed tools.
@@ -40,16 +52,30 @@ brew help
make -h
```
### Fedora 29/Debian-based Linux Distributions
#### Fedora 29/Debian-based Linux Distributions
Building the user docs should work out of the box on Fedora 29.
### Windows
#### Windows
Use "Bash on Ubuntu on Windows" for the same tools and capabilites as on a debian-based Linux.
Note: livereload seems not working on Windows.
# Lint
### Building the Docs
1. Run `make preview` to build the documentation.
1. Preview the built documentation locally at http://127.0.0.1:5500/.
### Cleanup
You can clean up all the build products and auto-installed Python stuff with:
```sh
make pristine
```
### Lint
Lint all:
@@ -69,15 +95,7 @@ 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:
```sh
make pristine
```
# Contributor info
# Information for Contributors
If you are interested in contributing to Scylla
docs, please read the Scylla open source page at
@@ -86,17 +104,8 @@ 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
# 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.