Migrate to Sphinx documentation (tezos-reward-distributor-organizatio…

…n#183)

* Added complete wiki to Sphinx documentation, please review!

docs/configuration.rst

@@ -1,24 +1,5 @@
-
 How to configure Tezos Reward Distributor?
-=====================================================
-
-Baker Configuration:
-------------------------
-
-Each baker has its own configuration and policy. A payment system should
-be flexible enough to cover needs of bakers. The application uses a yaml
-file for loading baker specific configurations.
-
-Configuration tool can be used to create baking configuration file
-interactively. Also an example configuration file is present under
-examples directory. For more information on configuration details, please
-see our wiki `page <https://github.com/habanoz/tezos-reward-distributor/wiki/Configuration>`_.
-
-TRD is designed to work as a linux service. It expects use of tezos
-signer for encrypted payment accounts. Unencrypted payment accounts can
-be used without tezos signer. If a payment account is encrypted and not
-configured to be signed by tezos signer, TRD will freeze. For more
-information on payment addresses please refer to our wiki `page <https://github.com/habanoz/tezos-reward-distributor/wiki/Payment-Address>`_.
+==========================================
 
 Email Setup
 ------------------------
@@ -33,3 +14,72 @@ fee.ini file contains details about transaction fees. Currently the fee
 value specified under DEFAULT domain is used as fee amount. It is in
 mutez.
 
+Baker Configuration:
+--------------------
+
+Each baker has its own configuration and policy. A payment system should
+be flexible enough to cover the needs of bakers. The application uses a yaml
+file for loading baker specific configurations.
+
+Configuration tool can be used to create baking configuration file
+interactively. Also an example configuration file is present under
+examples directory.
+By default configuration files are kept under ~/pymnt/cfg directory.
+Configuration directory can be changed with "-f" configuration option.
+Name of a configuration file should be the baker's address
+(e.g. tz1boot1pK9h2BVGXdyvfQSv8kd1LQM6H889.yaml).
+
+You can use configure.py tool to interactively create your configuration
+file, with ease.
+
+Available configuration parameters are:
+
+**baking_address**
+  Address of the baker. It must be an implicit account (tz1).
+  No alias is allowed.
+
+**owners_map**
+  A dictionary of PKH and ratio ( decimal in the range [0-1])
+  pairs. Each item in this dictionary represents PKH of each
+  balance owner and his ratio of the amount he owned in the
+  total baking balance. Implicit or originated addresses are
+  accepted. It is important that the sum of all ratios equals
+  to 1. This map is optional if owners do not want to be paid
+  for baking rewards, in this case, service fee remains in
+  baking balance.
+
+**founders_map**
+  A dictionary of PKH and ratio (decimal in the range [0-1])
+  pairs. Each item in this dictionary represents PKH of each
+  founder and his ratio of the shares coming from service fees.
+  Implicit or originated addresses are accepted. It is important
+  that the sum of all ratios equals to 1. This map is optional
+  if founders do not want to be paid from service fees, in
+  this case, service fee remains in baking balance.
+
+**service_fee**
+  A decimal in range [0-100]. This is evaluated as a percentage
+  value. If this value is set to 5, 5% of baking rewards are
+  kept as a service fee.
+
+**supporters_set**
+  A set of PKH values. Each PKH represents a supporter of the
+  baker. Supporters are not charged with a service fee. Founders
+  and balance owners are natural supporters, they are not
+  needed to be added.
+
+**specials_map**
+  A dictionary of PKH and fee (decimal in the range [0-100] )
+  pairs. This dictionary can be used to set special service
+  fee values for desired delegators.
+
+**delegator_pays_xfer_fee**
+  Default value is true. If set to false, the transfer fee for
+  each payment is paid by the delegate. Otherwise, the transfer
+  fee is deducted from the delegator reward.
+
+**payment_address**
+  This is the address where payments will be done from. A PKH
+  or alias of implicit or originated account is accepted. For
+  more information on the payment address configuration please
+  refer to the next section.

docs/contributers.rst

@@ -1,6 +1,23 @@
 For developers
 =====================================================
 
-Please refer to contributions guide_ on wiki pages.
+If you are interested in improving our project, this is just great! Our community looks forward to your contribution. Please follow this process:
 
-.. _guide : https://github.com/habanoz/tezos-reward-distributor/wiki/How-to-Contribute
+1. Start a bug/feature issue on GitHub about your proposed change. Continue discussion until a solution is decided.
+2. Fork the repo. Ideally, create a new branch from your fork for your contribution to make it easier to merge your changes back.
+3. Make your changes on the branch you hopefully created in Step 2. Be sure that your code passes existing unit tests. Please add unit tests for your work if appropriate. It usually is.
+4. Push your changes to your fork/branch in GitHub. Don't push it to your master! If you do it will make it harder to submit new changes later.
+5. Submit a pull request to the repo from your commit page on GitHub.
+
+
+Principles on the application evolution:
+
+1. Discuss the solution with repository owners and other community members. Start the development after everybody agrees on a solution. 
+2. Prefer the simpler solution. Try to make as fewer changes as possible. 
+3. Update documentation wherever it is meaningful.
+4. Create and run unit tests for the changes. Please do not sends PRs for untested changes. Payment domain requires the utmost responsibility.
+5. Follow naming conventions.
+6. Avoid code repetition. Make use of Object Oriented design principles when possible. 
+7. More configuration parameters do not always mean more flexibility. We do not want the application to turn into configuration hell which nobody can use.
+8. The idea of community members is very important because this repo is just a sequence of statements if nobody uses and benefit.
+9. A change will be accepted if it will benefit the community. Particular requests which only very few people will take advantage will not be accepted to leave the code as simple as possible. 

docs/index.rst

@@ -1,27 +1,52 @@
 Tezos Reward Distributor (Run & Forget) |Build Status|
 ======================================================
 
-DISCLAIMER : TEZOS REWARD DISTRIBUTOR IS PROVIDED AS IS. IT IS UNDER
-CONSTANT DEVELOPMENT. EVENT THOUGH IT IS WELL TESTED, PLEASE USE WITH
-CARE. ALWAYS MAKE A PRE-RUN IN DRY MODE BEFORE MAKING ACTUAL PAYMENTS.
-IF YOU WANT TO RUN IN SERVICE MODE DO IT AFTER YOU ARE CONFIDENT WITH
-THE APPLICATION. IN SERVICE MODE DO NOT UPDATE OFTEN.
+DISCLAIMER : TEZOS REWARD DISTRIBUTOR IS PROVIDED AS IS.
+IT IS UNDER CONSTANT DEVELOPMENT. EVENT THOUGH IT IS WELL
+TESTED, PLEASE USE IT WITH CARE. ALWAYS MAKE A PRE-RUN IN
+DRY MODE BEFORE MAKING ACTUAL PAYMENTS. IF YOU WANT TO
+RUN IN SERVICE MODE DO IT AFTER YOU ARE CONFIDENT WITH
+THE APPLICATION. IN SERVICE MODE ONLY UPDATE IF NEEDED.
 
 What is Tezos Reward Distributor?
 ------------------------------------------------
 
-TRD is a software for distributing baking rewards with delegators. This
-is not a script but a full scale application which can run in the
-background all the time. It can track cycles and make payments. It does
-not have to be used as a service, It can also be used interactively.
+TRD is a software for distributing staking rewards of
+delegators introduced in detail in this Medium article_.
+This is not a script but a full scale application which
+can continuously run in the background as a Linux service.
+It can track cycles and make payments. However it does
+not have to be used as a service, but it can also be
+used interactively.
 
-TRD supports complex payments, pays in batches, provides two back ends
-for calculations: rpc and tzstats. It was developed and tested extensively by
-the community. For more information, please check following Medium article_
-and the source code which can be found in the following Github_ repo.
+TRD supports complex payments, pays in batches, provides
+two back ends for calculations: rpc and tzstats_.
+Developed and tested extensively by the community and the
+source code which can be found in the following Github_ repo.
+
+**Important note:**
+
+The terms_ of tzstats note that a license is needed for
+the commercial use of the API!
+
+> If you wish to use the Data in a manner that is primarily
+> intended for or directed towards commercial advantage or
+> monetary compensation (such use, “Commercial Use”),
+> KIDTSUNAMI requires that you enter into a separate
+> commercial license agreement. Entering into a separate
+> commercial license allows us to protect KIDTSUNAMI’s
+> investment in the Data and to maintain the integrity of
+>the Data.
+>
+> Please contact us at [email protected] for more
+> information about Commercial Uses of our Data.
 
 .. _article : https://medium.com/@huseyinabanox/tezos-reward-distributor-e6588c4d27e7
 
+.. _tzstats : https://tzstats.com/
+
+.. _terms : https://tzstats.com/terms
+
 .. _Github : https://github.com/habanoz/tezos-reward-distributor
 
 .. toctree::
@@ -30,7 +55,11 @@ and the source code which can be found in the following Github_ repo.
 
    installation
    configuration
+   paymentaddress
+   tezossigner
+   tezossignerdocker
    run
+   linuxservice
    contributers
 
 Funding

docs/linuxservice.rst

@@ -0,0 +1,49 @@
+Run as Linux Service
+====================
+
+Alternatively, it is possible to add tezos-reward-distributer as a Linux service. It
+can run in the background.
+
+If docker is used, make sure user is in docker group
+
+::
+
+    sudo usermod -a -G docker $USER
+
+In order to set up the service with default configuration arguments, run
+the following command:
+
+::
+
+    sudo python3 service_add.py
+
+
+**Note:**
+
+If you do not want to use the default arguments, append any arguments
+you wish to change after service_add.py. They will be appended to
+main.py call. For example if you want to change configuration directory:
+
+::
+
+    sudo python3 service_add.py -f ~/payment/config/
+
+It will create a service file and use it to enable the service.
+Once enabled use following commands to start/stop the service.
+
+::
+
+    sudo systemctl start tezos-reward.service
+    sudo systemctl stop tezos-reward.service
+
+In order to see service status:
+
+::
+
+    systemctl status tezos-reward.service
+
+In order to see logs:
+
+::
+
+    journalctl --follow --unit=tezos-reward.service

docs/paymentaddress.rst

@@ -0,0 +1,44 @@
+Payment Address
+===============
+
+TRD is designed to work as a linux service. It expects 
+the usage of the Tezos signer for encrypted payment
+accounts. Unencrypted payment accounts can be used
+without tezos signer. If a payment account is encrypted
+and not configured to be signed by tezos signer,
+TRD will freeze.
+
+An address can only be used for payments if it satisfies the
+following criteria:
+
+- Public key of the address must be revealed. See tezos command
+  line interface on how to run reveal command on tezos client.
+  If an address is registered as delegate, there is no need to
+  run reveal command.
+
+  ::
+
+      ./tezos-client reveal key for <alias>
+
+- Secret key of the address must be known. If the payment
+  address is an implicit address (tz), its secret key must
+  be imported. If payment address is an originated address
+  (KT), secret key of the manager address must be imported.
+
+- If secret key is encrypted, tezos-signer must be used to
+  sign payments. For instructions on how to use signer,
+  please refer to the next section.
+
+- Use of unencrypted secret key is also possible. The
+  unencrypted secret key can be obtained from tezbox
+  web wallet. An unencrypted secret key can be imported
+  to the client using the command: 
+
+  ::
+
+      ./tezos-client import secret key <alias> unencrypted:edskXXXXX
+
+For more information about tezos command line interface please
+refer to the official Tezos documentation_.
+
+.. _documentation : http://tezos.gitlab.io/api/cli-commands.html

docs/run.rst

@@ -1,6 +1,9 @@
 How to run Tezos Reward Distributor?
 =====================================================
 
+Command Line Usage
+------------------------
+
 For a list of parameters, run:
 
 ::
@@ -9,35 +12,39 @@ For a list of parameters, run:
 
 The most common use case is to run in mainnet and start to make payments
 from last released rewards or continue making payments from the cycle
-last payment is done.
+last payment is done:
 
 ::
 
     python3 src/main.py
 
-For more example commands please see wiki `page <https://github.com/habanoz/tezos-reward-distributor/wiki/How-to-Run>`_.
-
+Make payments for a single cycle:
 
-Linux Service
-------------------------
+::
 
-Alternatively, it is possible to add tezos-reward-distributer as a Linux service. It
-can run in the background.
+    python3 src/main.py -C 42 -M 3 
 
-If docker is used, make sure user is in docker group
+Make pending payments and stop:
 
 ::
 
-    sudo usermod -a -G docker $USER
+    python3 src/main.py -M 2
 
-In order to set up the service with default configuration arguments, run
-the following command:
+Make pending payments beginning from a cycle and stop:
 
 ::
 
-    sudo python3 service_add.py
+    python3 src/main.py -C 30 -M 2
 
-For more information please refer to this wiki `page <https://github.com/habanoz/tezos-reward-distributor/wiki/Linux-Service>`_.
+Run in dry-run mode in zeronet, make payments from cycle 30 and exit:
 
+::
+
+    python3 src/main.py -D -N ZERONET -C 30 -M 3
 
+Run in dry-run mode in mainnet, make payments from cycle 30 onwards,
+for calculations use data provided by tezos node rpc interface:
+
+::
 
+    python3 src/main.py -C 30 -P rpc