Merge pull request #18 from zalando-incubator/first_usage_docs

First usage docs

.gitignore

@@ -68,6 +68,9 @@ instance/
 # IntelliJ stuff:
 .idea/
 
+# VSCode stuff:
+.vscode
+
 # Sphinx documentation
 docs/_build/
 

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.11][] - 2019-05-21
+
+### Added
+
+  - Documentation for first-time use
+  - README converted to RST format (README.rst)
+  - README linting
+
+### Removed
+
+  - README.md
+
 ## [1.2.10][] - 2019-05-21
 
 ### Fixed
@@ -81,6 +93,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Implemented `-v`/`--version` option to show Zelt version.
   - This changelog.
 
+[1.2.11]: https://github.com/zalando-incubator/zelt/compare/v1.2.10...v1.2.11
 [1.2.10]: https://github.com/zalando-incubator/zelt/compare/v1.2.9...v1.2.10
 [1.2.9]: https://github.com/zalando-incubator/zelt/compare/v1.2.8...v1.2.9
 [1.2.8]: https://github.com/zalando-incubator/zelt/compare/v1.2.7...v1.2.8

Makefile

@@ -9,6 +9,7 @@ test:
 .PHONY: lint
 lint:
 	poetry run pylint zelt > pylint-report.txt || true
+	poetry run python -m readme_renderer README.rst -o /dev/null
 
 .PHONY: docs
 docs:

README.rst

@@ -0,0 +1,187 @@
+.. image:: docs/_static/zelt.png
+    :alt: Zelt logo
+
+Zalando end-to-end load tester
+******************************
+
+.. image:: https://travis-ci.org/zalando-incubator/zelt.svg?branch=master
+   :alt: travis-ci status badge
+   :target: https://travis-ci.org/zalando-incubator/zelt
+
+.. image:: https://badgen.net/pypi/v/zelt
+   :alt: pypi version badge
+   :target: https://pypi.org/project/zelt
+
+.. image:: https://api.codacy.com/project/badge/Grade/a74dee2bbbd64da8951a3cec5059dda3
+   :alt: code quality badge
+   :target: https://www.codacy.com/app/bmaher/zelt
+
+.. image:: https://api.codacy.com/project/badge/Coverage/a74dee2bbbd64da8951a3cec5059dda3
+   :alt: test coverage badge
+   :target: https://www.codacy.com/app/bmaher/zelt
+
+.. image:: https://badgen.net/badge/code%20style/black/000
+   :alt: Code style: Black
+   :target: https://github.com/ambv/black
+
+|
+
+A **command-line tool** for orchestrating the deployment of
+Locust_ in Kubernetes_.
+
+Use it in conjunction with Transformer_ to run large-scale end-to-end
+load testing of your website.
+
+Prerequistes
+============
+
+-  `Python 3.6+`_
+
+Installation
+============
+
+Install using pip:
+
+.. code:: bash
+
+   pip install zelt
+
+Usage
+=====
+
+Example HAR files, locustfile, and manifests are included in the
+``examples/`` directory, try them out.
+
+**N.B** The cluster to deploy to is determined by your currently
+configured context. Ensure you are `using the correct cluster`_
+before using Zelt.
+
+Locustfile as input
+-------------------
+
+Zelt can deploy Locust with a locustfile to a cluster:
+
+.. code:: bash
+
+   zelt from-locustfile PATH_TO_LOCUSTFILE --manifests PATH_TO_MANIFESTS
+
+HAR files(s) as input
+---------------------
+
+Zelt can transform HAR file(s) into a locustfile and deploy it along
+with Locust to a cluster:
+
+.. code:: bash
+
+   zelt from-har PATH_TO_HAR_FILES --manifests PATH_TO_MANIFESTS
+
+**N.B** This requires
+Transformer_ to be installed. For more information about Transformer,
+please refer to `Transformer's documentation`_.
+
+Rescale a deployment
+--------------------
+
+Zelt can rescale the number of workers_ in a deployment it has made
+to a cluster:
+
+.. code:: bash
+
+   zelt rescale NUMBER_OF_WORKERS --manifests PATH_TO_MANIFESTS
+
+Delete a deployment
+-------------------
+
+Zelt can delete deployments it has made from a cluster:
+
+.. code:: bash
+
+   zelt delete --manifests PATH_TO_MANIFESTS
+
+Run Locust locally
+------------------
+
+Zelt can also run Locust locally by providing the ``--local/-l`` flag to
+either the ``from-har`` or ``from-locustfile`` command e.g.:
+
+.. code:: bash
+
+   zelt from-locustfile PATH_TO_LOCUSTFILE --local
+
+Use S3 for locustfile storage
+-----------------------------
+
+By default, Zelt uses a ConfigMap for storing the locustfile. ConfigMaps
+have a file-size limitation of ~2MB. If your locustfile is larger than
+this then you can use an S3 bucket for locustfile storage.
+
+To do so, add the following parameters to your Zelt command:
+
+-  ``--storage s3``: Switch to S3 storage
+-  ``--s3-bucket``: The name of your S3 bucket
+-  ``--s3-key``: The name of the file as stored in S3
+
+**N.B.** Zelt will *not* create the S3 bucket for you.
+
+**N.B.** Make sure to update your deployment manifest(s) to download the
+locustfile file from S3 instead of loading from the ConfigMap volume
+mount.
+
+Use a configuration file for Zelt options
+-----------------------------------------
+
+An alternative to specifying Zelt’s options on the command-line is to
+use a configuration file, for example:
+
+.. code:: bash
+
+   zelt from-har --config examples/config/config.yaml
+
+**N.B.** The configuration file’s keys are the same as the command-line
+option names but without the double dash (``--``).
+
+Documentation
+=============
+
+Take a look at our documentation_ for more details.
+
+Contributing
+============
+
+Please read `CONTRIBUTING.md <CONTRIBUTING.md>`__ for details on our
+process for submitting pull requests to us, and please ensure you follow
+the `CODE_OF_CONDUCT.md <CODE_OF_CONDUCT.md>`__.
+
+Versioning
+==========
+
+We use SemVer_ for versioning.
+
+Authors
+=======
+
+-  **Brian Maher** - `@bmaher`_
+-  **Oliwia Zaremba** - `@tortila`_
+-  **Thibaut Le Page** - `@thilp`_
+
+See also the list of `contributors <CONTRIBUTORS.md>`__ who participated
+in this project.
+
+License
+=======
+
+This project is licensed under the MIT License - see the
+`LICENSE <LICENSE>`__ file for details
+
+.. _Locust: https://locust.io/
+.. _Kubernetes: https://kubernetes.io/
+.. _Transformer: https://github.com/zalando-incubator/transformer
+.. _`Python 3.6+`: https://www.python.org/downloads/
+.. _`using the correct cluster`: https://kubernetes.io/docs/reference/kubectl/cheatsheet/#kubectl-context-and-configuration
+.. _`Transformer's documentation`: https://transformer.readthedocs.io/
+.. _workers: https://docs.locust.io/en/stable/running-locust-distributed.html
+.. _documentation: https://zelt.readthedocs.io/
+.. _`@bmaher`: https://github.com/bmaher
+.. _`@tortila`: https://github.com/tortila
+.. _`@thilp`: https://github.com/thilp
+.. _SemVer: http://semver.org/