Merge pull request #181 from twindb/docs-refresh

Docs refresh

.github/ISSUE_TEMPLATE.md

@@ -1,5 +1,4 @@
 * TwinDB Backup version:
-* Python version:
 * Operating System:
 
 ### Description

AUTHORS.rst

@@ -1,13 +1,5 @@
-=======
-Credits
-=======
 
 Development Lead
 ----------------
 
-* TwinDB Development Team <[email protected]>
-
-Contributors
-------------
-
-None yet. Why not be the first?
+Aleksandr Kuzminsky <[email protected]>

CONTRIBUTING.rst

@@ -21,6 +21,7 @@ If you are reporting a bug, please include:
 
 * Your operating system name and version.
 * Any details about your local setup that might be helpful in troubleshooting.
+  It is helpful if you post stack traces and a tool output with the ``--debug`` option.
 * Detailed steps to reproduce the bug.
 
 Fix Bugs
@@ -38,7 +39,7 @@ and "help wanted" is open to whoever wants to implement it.
 Write Documentation
 ~~~~~~~~~~~~~~~~~~~
 
-TwinDB Backup could always use more documentation, whether as part of the
+**TwinDB Backup** could always use more documentation, whether as part of the
 official TwinDB Backup docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
@@ -60,29 +61,39 @@ Get Started!
 Ready to contribute? Here's how to set up TwinDB Backup for local development.
 
 1. Fork the TwinDB Backup repo on GitHub.
-2. Clone your fork locally::
+2. Clone your fork locally:
+
+.. code-block:: console
 
     $ git clone [email protected]:your_name_here/backup.git twindb_backup
 
-3. Install your local copy into a virtualenv::
+3. Install your local copy into a virtualenv:
+
+.. code-block:: console
 
     $ make virtualenv
     $ source env/bin/activate
     $ make bootstrap
 
-4. Create a branch for local development::
+4. Create a branch for local development:
+
+.. code-block:: console
 
     $ git checkout -b name-of-your-bugfix-or-feature
 
-   Now you can make your changes locally.
+Now you can make your changes locally.
+
+5. When you're done making changes, check that your changes pass lint and the tests:
+
+.. code-block:: console
 
-5. When you're done making changes, check that your changes pass flake8 and the tests, including testing other Python versions with tox::
+    $ make lint
+    $ make test
 
-    $ make test-all
 
-   To get flake8 and tox, just pip install them into your virtualenv.
+6. Commit your changes and push your branch to GitHub:
 
-6. Commit your changes and push your branch to GitHub::
+.. code-block:: console
 
     $ git add .
     $ git commit -m "Your detailed description of your changes."
@@ -96,6 +107,7 @@ Pull Request Guidelines
 Before you submit a pull request, check that it meets these guidelines:
 
 - The pull request should include tests.
-- If the pull request adds functionality, the docs should be updated. Put your new functionality into a function with a docstring, and add the feature to the list in README.rst.
-- The pull request should work for Python 2.6 and 2.7.
-- Check https://travis-ci.org/twindb/backup/pull_requests and make sure that the tests pass for all supported Python versions.
+- If the pull request adds functionality, the docs should be updated.
+  Put your new functionality into a function with a docstring, and add the feature to the list in ``README.rst``.
+- The pull request should work for Python 2.7.
+- Check https://travis-ci.com/twindb/backup/pull_requests and make sure that the tests pass.

Makefile

@@ -115,7 +115,7 @@ coverage: ## check code coverage quickly with the default Python
 
 docs: ## generate Sphinx HTML documentation, including API docs
 	rm -f docs/twindb_backup.rst
-	rm -f docs/modules.rst
+	# rm -f docs/modules.rst
 	sphinx-apidoc -o docs/ twindb_backup
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html

README.rst

@@ -18,45 +18,104 @@ TwinDB Backup
     :alt: Join the chat at https://gitter.im/twindb/backup
 
 TwinDB Backup is a multipurpose tool for backing up MySQL and file system.
-It can store backup copies on a remote SSH server, Amazon S3 or Google Cloud Storage.
+It can store backup copies on a remote SSH server, Amazon S3 or
+Google Cloud Storage.
 
+TwinDB Backup accepts a backup copy stream from any of supported sources
+(MySQL Server, Percona Server, Percona XtraDB Cluster, or file system)
+and redirects the stream to a series of configurable modifiers.
 
-The tool can easily restore the backup copies.
+The modifiers can compress the stream, encrypt it, and save a copy of
+the stream on the local disk.
+
+Compression options:
+
+- gzip
+- bzip2
+- lbzip2
+- pigz
+
+Encryption options:
+
+- Public/private key encryption
+
+Because TwinDB Backup encrypts the stream itself it ensures transfer encryption
+as well as encryption at rest.
+
+After the stream passed all modifiers it is sent to one of configured
+backup destination. It can be:
+
+- Amazon S3 bucket
+- Google Cloud Storage bucket
+- Any server with SSH demon
+<<<<<<< HEAD
+
+.. figure:: https://user-images.githubusercontent.com/1763754/56677794-20901b80-6676-11e9-8f71-8de0b0b6f066.png
+    :width: 400px
+    :align: center
+    :height: 300px
+    :alt: TwinDB Backup Architecture
+    :figclass: align-center
+
+=======
+
+.. figure:: https://user-images.githubusercontent.com/1763754/56677794-20901b80-6676-11e9-8f71-8de0b0b6f066.png
+    :width: 400px
+    :align: center
+    :height: 300px
+    :alt: TwinDB Backup Architecture
+    :figclass: align-center
 
+>>>>>>> bdae2df9a45d7018641fb7c20681afc2fb659da2
+    TwinDB Backup Architecture
+
+The tool can easily restore the backup copies.
 Read full documentation on https://twindb-backup.readthedocs.io.
 
 
 Features
 --------
 
-**twindb-backup** key features:
+**TwinDB Backup** key features:
 
+- MySQL full and incremental backups
+- Zero seconds Recovery Point Objective (RPO) with MySQL binary log backups
+- Percona Xtradb Cluster backups
 - Files/directories backups
-- MySQL backups
-- Incremental MySQL backups
-- Encrypting backup copies
-
-**twindb-backup** store backups on:
+- Backups verification
+- Backups monitoring and alerting:
+    - Recovery Time Objective (RTO)
+    - Backups heartbeat
+    - Backups verification heartbeat
+- PCI-DSS compliant:
+    - Transfers encryption
+    - Encryption at rest
+- GDPR compliant:
+    - Strictly enforced retention policy
+
+**TwinDB Backup** storage options:
 
-- Remote SSH server
 - Amazon S3
 - Google Cloud Storage
-- Optionally save local copy
+- Remote SSH server
+- Optional local copy
 
 
 Other features:
 
 - Retention policy defines how many hourly/daily/weekly/monthly/yearly copies to keep
 - Separate retention policy for remote and local backup copies
-- Supports non-impacting Percona XtraDB Cluster backups
 - Email notifications
+- Datadog integration
 - cron configuration comes with a package
 
 
 How do I get set up?
-~~~~~~~~~~~~~~~~~~~~
+--------------------
 
-**twindb-backup** is distributed via package repositories. See installation instruction on https://packagecloud.io/twindb/main/install.
+**TwinDB Backup** is distributed via package repositories.
+
+See installation instruction on https://packagecloud.io/twindb/main/install.
 Once the repository for your operating system is configured, install the ``twindb-backup`` package.
 
 **On CentOS and RedHat**
@@ -75,16 +134,31 @@ Once the repository for your operating system is configured, install the ``twind
 
 
 Configuration
-~~~~~~~~~~~~~
+-------------
 Configuration is stored in ``/etc/twindb/twindb-backup.cfg``.
-See http://twindb-backup.readthedocs.io/en/master/usage.html for more details.
+See https://twindb-backup.readthedocs.io/ for more details.
+
+.. include:: ../AUTHORS.rst
 
 Credits
 -------
 
-This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
+- This package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.
+
+- TwinDB Backup uses `Percona Xtrabackup`_ for MySQL backups.
+- Contributors (in alphabetical order):
+
+  * `Andrew Ernst <https://github.com/ernstae>`_
+  * `Arda Beyazoğlu <https://github.com/ardabeyazoglu>`_
+  * `fonthead <https://github.com/fonthead>`_
+  * `Maksym Kryva <https://github.com/mkryva>`_
+  * `Manjot Singh <https://github.com/ManjotS>`_
+  * `Michael Rikmas <https://github.com/catyellow>`_
+  * `Ovais Tariq <https://github.com/ovaistariq>`_
+  * `Pim Widdershoven <https://github.com/piwi91>`_
+
+TwinDB Backup uses `Percona Xtrabackup`_ for MySQL backups.
 
 .. _Cookiecutter: https://github.com/audreyr/cookiecutter
 .. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage
-.. _instructions: https://twindb.com/twindb-software-repository/
-.. _wiki page: https://github.com/twindb/backup/wiki
+.. _`Percona Xtrabackup`: https://www.percona.com/software/mysql-database/percona-xtrabackup