Improve HOWTO markup

docs/HOWTO.rst

@@ -42,11 +42,12 @@ which can take some time.
 
 While not a requirement for running ElectrumX, it is intended to be
 run with supervisor software such as Daniel Bernstein's
-`daemontools`_, Gerald Pape's `runit`_ package or `systemd`.  These
+`daemontools`_, Gerrit Pape's `runit`_ package or :command:`systemd`.
-make administration of secure unix servers very easy, and I strongly
+These make administration of secure unix servers very easy, and I
-recommend you install one of these and familiarise yourself with them.
+strongly recommend you install one of these and familiarise yourself
-The instructions below and sample run scripts assume `daemontools`;
+with them.  The instructions below and sample run scripts assume
-adapting to `runit` should be trivial for someone used to either.
+``daemontools``; adapting to ``runit`` should be trivial for someone
+used to either.
 
 When building the database from the genesis block, ElectrumX has to
 flush large quantities of data to disk and its DB.  You will have a
@@ -81,14 +82,14 @@ Check out the code from Github::
     git clone https://github.com/kyuupichan/electrumx.git
     cd electrumx
 
-You can install with `setup.py` or run the code from the source tree
+You can install with :file:`setup.py` or run the code from the source
-or a copy of it.
+tree or a copy of it.
 
 You should create a standard user account to run the server under;
 your own is probably adequate unless paranoid.  The paranoid might
 also want to create another user account for the daemontools logging
 process.  The sample scripts and these instructions assume it is all
-under one account which I have called *electrumx*.
+under one account which I have called ``electrumx``.
 
 Next create a directory where the database will be stored and make it
 writeable by the electrumx account.  I recommend this directory live
@@ -110,30 +111,32 @@ to at least 2,500.
 
 Note that setting the limit in your shell does *NOT* affect ElectrumX
 unless you are invoking ElectrumX directly from your shell.  If you
-are using `systemd`, you need to set it in the `.service` file (see
+are using :command:`systemd`, you need to set it in the
-`contrib/systemd/electrumx.service`_).
+:file:`.service` file (see `contrib/systemd/electrumx.service`_).
 
 
 Using daemontools
 -----------------
 
 Next create a daemontools service directory; this only holds symlinks
-(see daemontools documentation).  The `svscan` program will ensure the
+(see daemontools documentation).  The :command:`svscan` program will
-servers in the directory are running by launching a `supervise`
+ensure the servers in the directory are running by launching a
-supervisor for the server and another for its logging process.  You
+:command:`supervise` supervisor for the server and another for its
-can run `svscan` under the *electrumx* account if that is the only one
+logging process.  You can run :command:`svscan` under the *electrumx*
-involved (server and logger) otherwise it will need to run as root so
+account if that is the only one involved (server and logger) otherwise
-that the user can be switched to electrumx.
+it will need to run as root so that the user can be switched to
+electrumx.
 
-Assuming this directory is called `service`, you would do one of::
+Assuming this directory is called :file:`service`, you would do one
+of::
 
     mkdir /service       # If running svscan as root
     mkdir ~/service      # As electrumx if running svscan as that a/c
 
-Next create a directory to hold the scripts that the `supervise`
+Next create a directory to hold the scripts that the
-process spawned by `svscan` will run - this directory must be readable
+:command:`supervise` process spawned by :command:`svscan` will run -
-by the `svscan` process.  Suppose this directory is called *scripts*,
+this directory must be readable by the :command:`svscan` process.
-you might do::
+Suppose this directory is called :file:`scripts`, you might do::
 
     mkdir -p ~/scripts/electrumx
 
@@ -141,20 +144,22 @@ Then copy the all sample scripts from the ElectrumX source tree there::
 
     cp -R /path/to/repo/electrumx/contrib/daemontools ~/scripts/electrumx
 
-This copies 3 things: the top level server run script, a log/ directory
+This copies 3 things: the top level server run script, a :file:`log/`
-with the logger run script, an env/ directory.
+directory with the logger :command:`run` script, an :file:`env/`
+directory.
 
-You need to configure the environment variables under env/ to your
+You need to configure the environment variables under :file:`env/` to
-setup, as explained in `ENVIRONMENT.rst`_.  ElectrumX server currently
+your setup, as explained in `ENVIRONMENT.rst`_.  ElectrumX server
-takes no command line arguments; all of its configuration is taken
+currently takes no command line arguments; all of its configuration is
-from its environment which is set up according to env/ directory (see
+taken from its environment which is set up according to :file:`env/`
-'envdir' man page).  Finally you need to change the log/run script to
+directory (see :manpage:`envdir` man page).  Finally you need to
-use the directory where you want the logs to be written by multilog.
+change the :command:`log/run` script to use the directory where you
-The directory need not exist as multilog will create it, but its
+want the logs to be written by multilog.  The directory need not exist
-parent directory must exist.
+as :command:`multilog` will create it, but its parent directory must
+exist.
 
-Now start the 'svscan' process.  This will not do much as the service
+Now start the :command:`svscan` process.  This will not do much as the
-directory is still empty::
+service directory is still empty::
 
     svscan ~/service & disown
 
@@ -172,23 +177,24 @@ You can see its logs with::
 Using systemd
 -------------
 
-This repository contains a sample systemd unit file that you can use to
+This repository contains a sample systemd unit file that you can use
-setup ElectrumX with systemd. Simply copy it to :code:`/etc/systemd/system`::
+to setup ElectrumX with systemd. Simply copy it to
+:file:`/etc/systemd/system`::
 
     cp contrib/systemd/electrumx.service /etc/systemd/system/
 
 The sample unit file assumes that the repository is located at
-:code:`/home/electrumx/electrumx`. If that differs on your system, you need to
+:file:`/home/electrumx/electrumx`. If that differs on your system, you
-change the unit file accordingly.
+need to change the unit file accordingly.
 
-You need to set a few configuration variables in :code:`/etc/electrumx.conf`,
+You need to set a few configuration variables in :file:`/etc/electrumx.conf`,
 see `ENVIRONMENT.rst`_ for the list of required variables.
 
-Now you can start ElectrumX using :code:`systemctl`::
+Now you can start ElectrumX using :command:`systemctl`::
 
     systemctl start electrumx
 
-You can use :code:`journalctl` to check the log output::
+You can use :command:`journalctl` to check the log output::
 
     journalctl -u electrumx -f
 
@@ -196,10 +202,11 @@ Once configured you may want to start ElectrumX at boot::
 
     systemctl enable electrumx
 
-**Warning**: systemd is aggressive in forcibly shutting down
+.. Warning:: systemd is aggressive in forcibly shutting down
-processes.  Depending on your hardware, ElectrumX can need several
+   processes.  Depending on your hardware, ElectrumX can need several
-minutes to flush cached data to disk during initial sync.  You should
+   minutes to flush cached data to disk during initial sync.  You
-set TimeoutStopSec to *at least* 10 mins in your `.service` file.
+   should set TimeoutStopSec to *at least* 10 mins in your
+   :file:`.service` file.
 
 
 Installing Python 3.6 under Ubuntu
@@ -213,11 +220,12 @@ in.  Because of this, it is easier to install Python 3.6.  See
 Installing on Raspberry Pi 3
 ----------------------------
 
-To install on the Raspberry Pi 3 you will need to update to the "stretch" distribution.
+To install on the Raspberry Pi 3 you will need to update to the
-See the full procedure in `contrib/raspberrypi3/install_electrumx.sh`_.
+``stretch`` distribution.  See the full procedure in
+`contrib/raspberrypi3/install_electrumx.sh`_.
 
-See also `contrib/raspberrypi3/run_electrumx.sh`_ for an easy way to configure and
+See also `contrib/raspberrypi3/run_electrumx.sh`_ for an easy way to
-launch electrumx.
+configure and launch electrumx.
 
 
 Sync Progress
@@ -225,8 +233,8 @@ Sync Progress
 
 Time taken to index the blockchain depends on your hardware of course.
 As Python is single-threaded most of the time only 1 core is kept
-busy.  ElectrumX uses Python's `asyncio` to prefill a cache of future
+busy.  ElectrumX uses Python's :mod:`asyncio` to prefill a cache of
-blocks asynchronously to keep the CPU busy processing the chain
+future blocks asynchronously to keep the CPU busy processing the chain
 without pausing.
 
 Consequently there will probably be only a minor boost in performance
@@ -234,12 +242,12 @@ if the daemon is on the same host.  It may even be beneficial to have
 the daemon on a *separate* machine so the machine doing the indexing
 has its caches and disk I/O tuned to that task only.
 
-The **CACHE_MB** environment variable controls the total cache size
+The :envvar:`CACHE_MB` environment variable controls the total cache size
 ElectrumX uses; see `ENVIRONMENT.rst`_ for caveats.
 
-Here is my experience with the current codebase, to given heights and
+Here is my experience with the codebase of year ago (the current
-rough wall-time.  The period from heights 363,000 to 378,000 is the
+codebase is faster), to given heights and rough wall-time.  The period
-most sluggish::
+from heights 363,000 to 378,000 is the most sluggish::
 
                  Machine A     Machine B
   181,000          25m 00s      5m 30s
@@ -252,28 +260,32 @@ most sluggish::
 
 *Machine A*: a low-spec 2011 1.6GHz AMD E-350 dual-core fanless CPU,
 8GB RAM and a DragonFlyBSD UFS fileystem on an SSD.  It requests
-blocks over the LAN from a bitcoind on machine B.  **DB_CACHE** the
+blocks over the LAN from a bitcoind on machine B.  :envvar:`DB_CACHE`
-default of 1,200.  LevelDB.
+the default of 1,200.  LevelDB.
 
 *Machine B*: a late 2012 iMac running Sierra 10.12.2, 2.9GHz quad-core
 Intel i5 CPU with an HDD and 24GB RAM.  Running bitcoind on the same
-machine.  **DB_CACHE** set to 1,800.  LevelDB.
+machine.  :envvar:`DB_CACHE` set to 1,800.  LevelDB.
 
 For chains other than bitcoin-mainnet sychronization should be much
 faster.
 
-**Note**: ElectrumX will not serve normal client connections until it
+.. note:: ElectrumX will not serve normal client connections until it
-has fully synchronized and caught up with your daemon.  However
+          has fully synchronized and caught up with your daemon.
-LocalRPC connections are served at all times.
+          However LocalRPC connections are served at all times.
 
 
 Terminating ElectrumX
 =====================
 
 The preferred way to terminate the server process is to send it the
-**stop** RPC command, or alternatively on Unix the INT or TERM
+``stop`` RPC command::
-signals.  For a daemontools supervised process this can be done by
+
-bringing it down like so::
+  electrumx_rpy.py stop
+
+or alternatively on Unix the ``INT`` or ``TERM`` signals.  For a
+daemontools supervised process this can be done by bringing it down
+like so::
 
     svc -d ~/service/electrumx
 
@@ -297,9 +309,10 @@ You can see the status of a running service with::
 
     svstat ~/service/electrumx
 
-`svscan` can of course handle multiple services simultaneously from
+:command:`svscan` can of course handle multiple services
-the same service directory, such as a testnet or altcoin server.  See
+simultaneously from the same service directory, such as a testnet or
-the man pages of these various commands for more information.
+altcoin server.  See the man pages of these various commands for more
+information.
 
 
 Understanding the Logs
@@ -362,11 +375,12 @@ to height 280,000 is should be fairly accurate.
 Creating an self-signed SSL certificate
 =======================================
 
-These instructions are based on those of the `electrum-server` documentation.
+These instructions are based on those of the ``electrum-server``
+documentation.
 
 To run an SSL server you need to generate a self-signed certificate
-using openssl.  Alternatively you could not set **SSL_PORT** in the
+using openssl.  Alternatively you could not set :envvar:`SSL_PORT` in
-environment and not serve over SSL, but this is not recommended.
+the environment and not serve over SSL, but this is not recommended.
 
 Use the sample code below to create a self-signed cert with a
 recommended validity of 5 years. You may supply any information for
@@ -385,8 +399,9 @@ challenge password just leave it empty and press enter::
     ...
     $ openssl x509 -req -days 1825 -in server.csr -signkey server.key -out server.crt
 
-The `server.crt` file goes in **SSL_CERTFILE** and `server.key` in
+The :file:`server.crt` file goes in :envvar:`SSL_CERTFILE` and
-**SSL_KEYFILE** in the server process's environment.
+:file:`server.key` in :envvar:`SSL_KEYFILE` in the server process's
+environment.
 
 Starting with Electrum 1.9, the client will learn and locally cache
 the SSL certificate for your server upon the first request to prevent
@@ -400,14 +415,16 @@ copy of your certificate and key in case you need to restore them.
 Running on a privileged port
 ============================
 
-You may choose to run electrumx on a different port than 50001 / 50002.
+You may choose to run electrumx on a different port than 50001
-If you choose a privileged port ( < 1024 ) it makes sense to make use of a iptables NAT rule.
+/ 50002.  If you choose a privileged port ( < 1024 ) it makes sense to
+make use of a iptables NAT rule.
 
-An example, which will forward Port 110 to the internal port 50002 follows:
+An example, which will forward Port 110 to the internal port 50002 follows::
 
     iptables -t nat -A PREROUTING -p tcp --dport 110 -j DNAT --to-destination 127.0.0.1:50002
 
-You can then set the port as follows and advertise the service externally on the privileged port
+You can then set the port as follows and advertise the service externally on the privileged port::
+
     REPORT_SSL_PORT=110