Improve envvar docs

docs/ENVIRONMENT.rst

@@ -16,188 +16,194 @@ must set **HOST** appropriately; see below.
 
 
 Required
---------
+========
 
 These environment variables are always required:
 
-* **COIN**
+.. envvar:: COIN
 
-  Must be a *NAME* from one of the **Coin** classes in
+  Must be a :attr:`NAME` from one of the :class:`Coin` classes in
   `lib/coins.py`_.
 
-* **DB_DIRECTORY**
+.. envvar:: DB_DIRECTORY
 
   The path to the database directory.  Relative paths should be
   relative to the parent process working directory.  This is the
   directory of the `run` script if you use it.
 
-* **DAEMON_URL**
+.. envvar:: DAEMON_URL
 
   A comma-separated list of daemon URLs.  If more than one is provided
   ElectrumX will initially connect to the first, and failover to
   subsequent ones round-robin style if one stops working.
 
-  The generic form of a daemon URL is:
+  The generic form of a daemon URL is::
 
-     `http://username:password@hostname:port/`
+     http://username:password@hostname:port/
 
-  The leading `http://` is optional, as is the trailing slash.  The
+  The leading ``http://`` is optional, as is the trailing slash.  The
-  `:port` part is also optional and will default to the standard RPC
+  ``:port`` part is also optional and will default to the standard RPC
-  port for **COIN** and **NET** if omitted.
+  port for :envvar:`COIN` and :envvar:`NET` if omitted.
 
 
-For the `run` script
+For the ``run`` script
---------------------
+======================
 
-The following are required if you use the `run` script:
+The following are required if you use the ``run`` script:
 
-* **ELECTRUMX**
+.. envvar:: ELECTRUMX
 
   The path to the electrumx_server.py script.  Relative paths should
-  be relative to the directory of the `run` script.
+  be relative to the directory of the ``run`` script.
 
-* **USERNAME**
+.. envvar:: USERNAME
 
   The username the server will run as.
 
 
 Miscellaneous
--------------
+=============
 
 These environment variables are optional:
 
-* **LOG_FORMAT**
+.. envvar:: LOG_FORMAT
 
   The Python logging `format string
   <https://docs.python.org/3/library/logging.html#logrecord-attributes>`_
-  to use.  Defaults to `%(levelname)s:%(name)s:%(message)s`.
+  to use.  Defaults to ``%(levelname)s:%(name)s:%(message)s``.
 
-* **ALLOW_ROOT**
+.. envvar:: ALLOW_ROOT
 
   Set this environment variable to anything non-empty to allow running
   ElectrumX as root.
 
-* **NET**
+.. envvar:: NET
 
-  Must be a *NET* from one of the **Coin** classes in `lib/coins.py`_.
+  Must be a :envvar:`NET` from one of the **Coin** classes in
-  Defaults to `mainnet`.
+  `lib/coins.py`_.  Defaults to ``mainnet``.
 
-* **DB_ENGINE**
+.. envvar:: DB_ENGINE
 
   Database engine for the UTXO and history database.  The default is
-  `leveldb`.  The other alternative is `rocksdb`.  You will need to
+  ``leveldb``.  The other alternative is ``rocksdb``.  You will need
-  install the appropriate python package for your engine.  The value
+  to install the appropriate python package for your engine.  The
-  is not case sensitive.
+  value is not case sensitive.
 
-* **HOST**
+.. envvar:: HOST
 
   The host or IP address that the TCP and SSL servers will use when
-  binding listening sockets.  Defaults to `localhost`.  To listen on
+  binding listening sockets.  Defaults to ``localhost``.  To listen on
   multiple specific addresses specify a comma-separated list.  Set to
   an empty string to listen on all available interfaces (likely both
   IPv4 and IPv6).
 
-* **TCP_PORT**
+.. envvar:: TCP_PORT
 
-  If set ElectrumX will serve TCP clients on **HOST**:**TCP_PORT**.
+  If set ElectrumX will serve TCP clients on
+  :envvar:`HOST`\::envvar:`TCP_PORT`.
 
-  **Note**: ElectrumX will not serve TCP connections until it has
+  .. note:: ElectrumX will not serve TCP connections until it has
-  fully caught up with your daemon.
+            fully caught up with your daemon.
 
-* **SSL_PORT**
+.. envvar:: SSL_PORT
 
-  If set ElectrumX will serve SSL clients on **HOST**:**SSL_PORT**.
+  If set ElectrumX will serve SSL clients on
-  If set then SSL_CERTFILE and SSL_KEYFILE must be defined and be
+  :envvar:`HOST`\::envvar:`SSL_PORT`.  If set then
-  filesystem paths to those SSL files.
+  :envvar:`SSL_CERTFILE` and :envvar:`SSL_KEYFILE` must be defined
+  environment variables with values the filesystem paths to those SSL
+  files.
 
-  **Note**: ElectrumX will not serve SSL connections until it has
+  .. note:: ElectrumX will not serve SSL connections until it has
-  fully caught up with your daemon.
+            fully caught up with your daemon.
 
-* **RPC_HOST**
+.. envvar:: RPC_HOST
 
   The host or IP address that the RPC server will listen on and
-  defaults to `localhost`.  To listen on multiple specific addresses
+  defaults to ``localhost``.  To listen on multiple specific addresses
   specify a comma-separated list.  Servers with unusual networking
-  setups might want to specify e.g. `::1` or `127.0.0.1` explicitly
+  setups might want to specify e.g. ``::1`` or ``127.0.0.1``
-  rather than defaulting to `localhost`.
+  explicitly rather than defaulting to ``localhost``.
 
   An empty string (normally indicating all interfaces) is interpreted
-  as `localhost`, because allowing access to the server's RPC
+  as ``localhost``, because allowing access to the server's RPC
-  interface to arbitrary connections across the internet is not a
+  interface to arbitrary connections across the internet is not a good
-  good idea.
+  idea.
 
-* **RPC_PORT**
+.. envvar:: RPC_PORT
 
   ElectrumX will listen on this port for local RPC connections.
   ElectrumX listens for RPC connections unless this is explicitly set
-  to blank.  The default depends on **COIN** and **NET** (e.g., 8000
+  to blank.  The default depends on :envvar:`COIN` and :attr:`NET`
-  for Bitcoin mainnet) if not set, as indicated in `lib/coins.py`_.
+  (e.g., 8000 for Bitcoin mainnet) if not set, as indicated in
+  `lib/coins.py`_.
 
-* **DONATION_ADDRESS**
+.. envvar:: DONATION_ADDRESS
 
   The server donation address reported to Electrum clients.  Defaults
   to empty, which Electrum interprets as meaning there is none.
 
-* **BANNER_FILE**
+.. envvar:: BANNER_FILE
 
   The path to a banner file to serve to clients in Electrum's
   "Console" tab.  Relative file paths must be relative to
-  **DB_DIRECTORY**.  The banner file is re-read for each new client.
+  :envvar:`DB_DIRECTORY`.  The banner file is re-read for each new
+  client.
 
   You can place several meta-variables in your banner file, which will be
   replaced before serving to a client.
 
-  + **$SERVER_VERSION** is replaced with the ElectrumX version you are
+  + ``$SERVER_VERSION`` is replaced with the ElectrumX version you are
-    running, such as *1.0.10*.
+    running, such as ``1.0.10``.
-  + **$SERVER_SUBVERSION** is replaced with the ElectrumX user agent
+  + ``$SERVER_SUBVERSION`` is replaced with the ElectrumX user agent
-    string.  For example, `ElectrumX 1.0.10`.
+    string.  For example, ``ElectrumX 1.0.10``.
-  + **$DAEMON_VERSION** is replaced with the daemon's version as a
+  + ``$DAEMON_VERSION`` is replaced with the daemon's version as a
-    dot-separated string. For example *0.12.1*.
+    dot-separated string. For example ``0.12.1``.
-  + **$DAEMON_SUBVERSION** is replaced with the daemon's user agent
+  + ``$DAEMON_SUBVERSION`` is replaced with the daemon's user agent
-    string.  For example, `/BitcoinUnlimited:0.12.1(EB16; AD4)/`.
+    string.  For example, ``/BitcoinUnlimited:0.12.1(EB16; AD4)/``.
-  + **$DONATION_ADDRESS** is replaced with the address from the
+  + ``$DONATION_ADDRESS`` is replaced with the address from the
-    **DONATION_ADDRESS** environment variable.
+    :envvar:`DONATION_ADDRESS` environment variable.
 
-  See https://github.com/shsmith/electrumx-banner-updater for a script
+  See `here <https://github.com/shsmith/electrumx-banner-updater>`_
-  that updates a banner file periodically with useful statistics about
+  for a script that updates a banner file periodically with useful
-  fees, last block time and height, etc.
+  statistics about fees, last block time and height, etc.
 
-* **TOR_BANNER_FILE**
+.. envvar:: TOR_BANNER_FILE
 
-  As for **BANNER_FILE** (which is also the default) but shown to
+  As for :envvar:`BANNER_FILE` (which is also the default) but shown
-  incoming connections believed to be to your Tor hidden service.
+  to incoming connections believed to be to your Tor hidden service.
 
-* **ANON_LOGS**
+.. envvar:: ANON_LOGS
 
   Set to anything non-empty to replace IP addresses in logs with
-  redacted text like 'xx.xx.xx.xx:xxx'.  By default IP addresses will
+  redacted text like ``xx.xx.xx.xx:xxx``.  By default IP addresses
-  be written to logs.
+  will be written to logs.
 
-* **LOG_SESSIONS**
+.. envvar:: LOG_SESSIONS
 
   The number of seconds between printing session statistics to the
-  log.  The output is identical to the **sessions** RPC command except
+  log.  The output is identical to the :ref:`sessions` RPC command
-  that **ANON_LOGS** is honoured.  Defaults to 3600.  Set to zero to
+  except that :envvar:`ANON_LOGS` is honoured.  Defaults to 3600.  Set
-  suppress this logging.
+  to zero to suppress this logging.
 
-* **REORG_LIMIT**
+.. envvar:: REORG_LIMIT
 
   The maximum number of blocks to be able to handle in a chain
   reorganisation.  ElectrumX retains some fairly compact undo
   information for this many blocks in levelDB.  The default is a
-  function of **COIN** and **NET**; for Bitcoin mainnet it is 200.
+  function of :envvar:`COIN` and :attr:`NET`; for Bitcoin mainnet it
+  is 200.
 
-* **EVENT_LOOP_POLICY**
+.. envvar:: EVENT_LOOP_POLICY
 
   The name of an event loop policy to replace the default asyncio
-  policy, if any.  At present only `uvloop` is accepted, in which case
+  policy, if any.  At present only ``uvloop`` is accepted, in which
-  you must have installed the `uvloop`_ Python package.
+  case you must have installed the `uvloop`_ Python package.
 
   If you are not sure what this means leave it unset.
 
 
 Resource Usage Limits
----------------------
+=====================
 
 The following environment variables are all optional and help to limit
 server resource consumption and prevent simple DoS.
@@ -207,13 +213,13 @@ Address subscriptions in ElectrumX are very cheap - they consume about
 two subscription-related defaults below are low and encourage you to
 raise them.
 
-* **MAX_SESSIONS**
+.. envvar:: MAX_SESSIONS
 
   The maximum number of incoming connections.  Once reached, TCP and
   SSL listening sockets are closed until the session count drops
   naturally to 95% of the limit.  Defaults to 1,000.
 
-* **MAX_SEND**
+.. envvar:: MAX_SEND
 
   The maximum size of a response message to send over the wire, in
   bytes.  Defaults to 1,000,000.  Values smaller than 350,000 are
@@ -222,28 +228,28 @@ raise them.
 
   The Electrum protocol has a flaw in that address histories must be
   served all at once or not at all, an obvious avenue for abuse.
-  **MAX_SEND** is a stop-gap until the protocol is improved to admit
+  :envvar:`MAX_SEND` is a stop-gap until the protocol is improved to
-  incremental history requests.  Each history entry is approximately
+  admit incremental history requests.  Each history entry is
-  100 bytes so the default is equivalent to a history limit of around
+  approximately 100 bytes so the default is equivalent to a history
-  10,000 entries, which should be ample for most legitimate users.  If
+  limit of around 10,000 entries, which should be ample for most
-  you use a higher default bear in mind one client can request history
+  legitimate users.  If you use a higher default bear in mind one
-  for multiple addresses.  Also note that the largest raw transaction
+  client can request history for multiple addresses.  Also note that
-  you will be able to serve to a client is just under half of
+  the largest raw transaction you will be able to serve to a client is
-  MAX_SEND, as each raw byte becomes 2 hexadecimal ASCII characters on
+  just under half of :envvar:`MAX_SEND`, as each raw byte becomes 2
-  the wire.  Very few transactions on Bitcoin mainnet are over 500KB
+  hexadecimal ASCII characters on the wire.  Very few transactions on
-  in size.
+  Bitcoin mainnet are over 500KB in size.
 
-* **MAX_SUBS**
+.. envvar:: MAX_SUBS
 
   The maximum number of address subscriptions across all sessions.
   Defaults to 250,000.
 
-* **MAX_SESSION_SUBS**
+.. envvar:: MAX_SESSION_SUBS
 
   The maximum number of address subscriptions permitted to a single
   session.  Defaults to 50,000.
 
-* **BANDWIDTH_LIMIT**
+.. envvar:: BANDWIDTH_LIMIT
 
   Per-session periodic bandwidth usage limit in bytes.  This is a soft,
   not hard, limit.  Currently the period is hard-coded to be one hour.
@@ -261,7 +267,7 @@ raise them.
   Bandwidth usage is gradually reduced over time by "refunding" a
   proportional part of the limit every now and then.
 
-* **SESSION_TIMEOUT**
+.. envvar:: SESSION_TIMEOUT
 
   An integer number of seconds defaulting to 600.  Sessions with no
   activity for longer than this are disconnected.  Properly
@@ -270,10 +276,10 @@ raise them.
 
 
 Peer Discovery
---------------
+==============
 
-In response to the `server.peers.subscribe` RPC call, ElectrumX will
+In response to the :func:`server.peers.subscribe` RPC call, ElectrumX
-only return peer servers that it has recently connected to and
+will only return peer servers that it has recently connected to and
 verified basic functionality.
 
 If you are not running a Tor proxy ElectrumX will be unable to connect
@@ -287,19 +293,20 @@ ElectrumX will perform peer-discovery by default and announce itself
 to other peers.  If your server is private you may wish to disable
 some of this.
 
-* **PEER_DISCOVERY**
+.. envvar:: PEER_DISCOVERY
 
-  This environment variable is case-insensitive and defaults to `on`.
+  This environment variable is case-insensitive and defaults to
+  ``on``.
 
-  If `on`, ElectrumX will occasionally connect to and verify its
+  If ``on``, ElectrumX will occasionally connect to and verify its
   network of peer servers.
 
-  If `off`, peer discovery is disabled and a hard-coded default list
+  If ``off``, peer discovery is disabled and a hard-coded default list
-  of servers will be read in and served.  If set to `self` then peer
+  of servers will be read in and served.  If set to ``self`` then peer
   discovery is disabled and the server will only return itself in the
   peers list.
 
-* **PEER_ANNOUNCE**
+.. envvar:: PEER_ANNOUNCE
 
   Set this environment variable to empty to disable announcing itself.
   If not defined, or non-empty, ElectrumX will announce itself to
@@ -310,21 +317,22 @@ some of this.
   peer discovery if it notices it is not present in the peer's
   returned list.
 
-* **FORCE_PROXY**
+.. envvar:: FORCE_PROXY
 
   By default peer discovery happens over the clear internet.  Set this
   to non-empty to force peer discovery to be done via the proxy.  This
   might be useful if you are running a Tor service exclusively and
   wish to keep your IP address private.
 
-* **TOR_PROXY_HOST**
+.. envvar:: TOR_PROXY_HOST
 
-  The host where your Tor proxy is running.  Defaults to *localhost*.
+  The host where your Tor proxy is running.  Defaults to
+  ``localhost``.
 
   If you are not running a Tor proxy just leave this environment
   variable undefined.
 
-* **TOR_PROXY_PORT**
+.. envvar:: TOR_PROXY_PORT
 
   The port on which the Tor proxy is running.  If not set, ElectrumX
   will autodetect any proxy running on the usual ports 9050 (Tor),
@@ -332,50 +340,52 @@ some of this.
 
 
 Server Advertising
-------------------
+==================
 
 These environment variables affect how your server is advertised
 by peer discovery (if enabled).
 
-* **REPORT_HOST**
+.. envvar:: REPORT_HOST
 
   The clearnet host to advertise.  If not set, no clearnet host is
   advertised.
 
-* **REPORT_TCP_PORT**
+.. envvar:: REPORT_TCP_PORT
 
-  The clearnet TCP port to advertise if **REPORT_HOST** is set.
+  The clearnet TCP port to advertise if :envvar:`REPORT_HOST` is set.
-  Defaults to **TCP_PORT**.  '0' disables publishing a TCP port.
+  Defaults to :envvar:`TCP_PORT`.  ``0`` disables publishing a TCP
+  port.
 
-* **REPORT_SSL_PORT**
+.. envvar:: REPORT_SSL_PORT
 
-  The clearnet SSL port to advertise if **REPORT_HOST** is set.
+  The clearnet SSL port to advertise if :envvar:`REPORT_HOST` is set.
-  Defaults to **SSL_PORT**.  '0' disables publishing an SSL port.
+  Defaults to :envvar:`SSL_PORT`.  ``0`` disables publishing an SSL
+  port.
 
-* **REPORT_HOST_TOR**
+.. envvar:: REPORT_HOST_TOR
 
   If you wish run a Tor service, this is the Tor host name to
-  advertise and must end with `.onion`.
+  advertise and must end with ``.onion``.
 
-* **REPORT_TCP_PORT_TOR**
+.. envvar:: REPORT_TCP_PORT_TOR
 
   The Tor TCP port to advertise.  The default is the clearnet
-  **REPORT_TCP_PORT**, unless disabled or it is '0', otherwise
+  :envvar:`REPORT_TCP_PORT`, unless disabled or it is ``0``, otherwise
-  **TCP_PORT**.  '0' disables publishing a Tor TCP port.
+  :envvar:`TCP_PORT`.  ``0`` disables publishing a Tor TCP port.
 
-* **REPORT_SSL_PORT_TOR**
+.. envvar:: REPORT_SSL_PORT_TOR
 
   The Tor SSL port to advertise.  The default is the clearnet
-  **REPORT_SSL_PORT**, unless disabled or it is '0', otherwise
+  :envvar:`REPORT_SSL_PORT`, unless disabled or it is ``0``, otherwise
-  **SSL_PORT**.  '0' disables publishing a Tor SSL port.
+  :envvar:`SSL_PORT`.  ``0`` disables publishing a Tor SSL port.
 
-  **NOTE**: Certificate-Authority signed certificates don't work over
+  .. note:: Certificate-Authority signed certificates don't work over
-  Tor, so you should set **REPORT_SSL_PORT_TOR** to 0 if yours is not
+            Tor, so you should set :envvar:`REPORT_SSL_PORT_TOR` to
-  self-signed.
+            ``0`` if yours is not self-signed.
 
 
 Cache
------
+=====
 
 If synchronizing from the Genesis block your performance might change
 by tweaking the cache size.  Cache size is only checked roughly every
@@ -387,7 +397,7 @@ your available physical RAM:
 
 .. _CACHE:
 
-* **CACHE_MB**
+.. envvar:: CACHE_MB
 
   The amount of cache, in MB, to use.  The default is 1,200.
 
@@ -400,9 +410,8 @@ your available physical RAM:
   fact performance begins to fall, probably because LevelDB already
   caches, and also because of Python GC.
 
-  I do not recommend raising this above 2000.  If upgrading from prior
+  I do not recommend raising this above 2000.
-  versions, a value of 90% of the sum of the old UTXO_MB and HIST_MB
-  variables is roughly equivalent.
 
-.. _lib/coins.py: https://github.com/kyuupichan/electrumx/blob/master/lib/coins.py
+.. _lib/coins.py:
+   https://github.com/kyuupichan/electrumx/blob/master/lib/coins.py
 .. _uvloop: https://pypi.python.org/pypi/uvloop

docs/conf.py

@@ -92,7 +92,7 @@ html_theme_options = {
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-html_static_path = ['_static']
+# html_static_path = ['_static']
 
 # Custom sidebar templates, must be a dictionary that maps document names
 # to template names.

docs/rpc-interface.rst

@@ -172,6 +172,8 @@ That number of blocks will be backed up - using undo information
 stored in ElectrumX's database - and then ElectrumX will move forwards
 on the daemon's main chain to its current height.
 
+.. _sessions:
+
 sessions
 --------