Merge pull request #3 from rumpelsepp/master

Some rst fixes

dev/building.rst

@@ -41,7 +41,7 @@ Building (Unix)
 -  Install the prerequisites.
 -  Open a terminal.
 
-.. code:: bash
+.. code-block:: bash
 
     # This should output "go version go1.3" or higher.
     $ go version
@@ -67,9 +67,7 @@ Building (Windows)
 ------------------
 
 -  Install the prerequisites.
--  Open a ``cmd`` Window.
+-  Open a ``cmd`` Window::
-
-.. code:: bash
 
     # This should output "go version go1.3" or higher.
     > go version

dev/device-ids.rst

@@ -119,21 +119,21 @@ TLS handshake performed. As part of the handshake both devices present
 their certificates. Once the handshake has completed and the peer
 certificate is known, the following steps are performed.
 
-1. Calculate the remote device ID by using the process above on the
+#. Calculate the remote device ID by using the process above on the
    received certificate.
 
-2. Weed out a few possible misconfigurations - i.e. if the device ID is
+#. Weed out a few possible misconfigurations - i.e. if the device ID is
    that of the local device or of a device we already have an active
    connection to. Drop the connection in these cases.
 
-3. Verify the remote device ID against the configuration. If it is not a
+#. Verify the remote device ID against the configuration. If it is not a
    device ID we are expecting to talk to, drop the connection.
 
-4. Verify the certificate ``CommonName`` against the configuration. By
+#. Verify the certificate ``CommonName`` against the configuration. By
    default, we expect it to be ``syncthing``, but when using custom
    certificates this can be changed.
 
-5. If everything checks out so far, accept the connection.
+#. If everything checks out so far, accept the connection.
 
 An Aside About Collisions
 -------------------------

dev/release.rst

@@ -29,7 +29,7 @@ happening that should be fixed - requires investigation).
 Create a new, signed tag on master, with the version as comment, and
 push it:
 
-.. code:: bash
+.. code-block:: bash
 
     $ git tag -a -s -u release@syncthing.net -m v0.10.15 v0.10.15
     $ git push --tags

events/configsaved.rst

@@ -4,7 +4,7 @@ ConfigSaved
 Emitted after the config has been saved by the user or by Syncthing
 itself.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 50,

events/deviceconnected.rst

@@ -3,7 +3,7 @@ DeviceConnected
 
 Generated each time a connection to a device has been established.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 2,

events/devicedisconnected.rst

@@ -3,7 +3,7 @@ DeviceDisconnected
 
 Generated each time a connection to a device has been terminated.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 48,

events/devicediscovered.rst

@@ -3,7 +3,7 @@ DeviceDiscovered
 
 Emitted when a new device is discovered using local discovery.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 13,

events/devicerejected.rst

@@ -4,7 +4,7 @@ DeviceRejected
 Emitted when there is a connection from a device we are not configured
 to talk to.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 24,

events/downloadprogress.rst

@@ -5,7 +5,7 @@ Emitted during file downloads for each folder for each file. By default
 only a single file in a folder is handled at the same time, but custom
 configuration can cause multiple files to be shown.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 221,

events/foldercompletion.rst

@@ -6,7 +6,7 @@ contents for a folder changes. It contains the completion percentage for
 a given remote device and is emitted once per currently connected remote
 device.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 84,

events/folderrejected.rst

@@ -4,7 +4,7 @@ FolderRejected
 Emitted when a device sends index information for a folder we do not
 have, or have but do not share with the device in question.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 27,

events/foldersummary.rst

@@ -5,7 +5,7 @@ The FolderSummary event is emitted when folder contents have changed
 locally. This can be used to calculate the current local completion
 state.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 16,

events/itemfinished.rst

@@ -4,7 +4,7 @@ ItemFinished
 Generated when Syncthing ends synchronizing a file to a newer version. A
 successful operation:
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 93,
@@ -21,7 +21,7 @@ successful operation:
 
 An unsuccessful operation:
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 44,

events/itemstarted.rst

@@ -3,7 +3,7 @@ ItemStarted
 
 Generated when Syncthing begins synchronizing a file to a newer version.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 93,

events/localindexupdated.rst

@@ -5,7 +5,7 @@ Generated when the local index information has changed, due to
 synchronizing one or more items from the cluster or discovering local
 changes during a scan.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 59,

events/ping.rst

@@ -5,7 +5,7 @@ The Ping event is generated automatically every 60 seconds. This means
 that even in the absence of any other activity, the event polling HTTP
 request will return within a minute.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 46,

events/remoteindexupdated.rst

@@ -3,7 +3,7 @@ RemoteIndexUpdated
 
 Generated each time new index information is received from a device.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 44,

events/starting.rst

@@ -4,7 +4,7 @@ Starting
 Emitted exactly once, when Syncthing starts, before parsing
 configuration etc.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 1,

events/startupcomplete.rst

@@ -4,7 +4,7 @@ StartupCompleted
 Emitted exactly once, when initialization is complete and Syncthing is
 ready to start exchanging data with other devices.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 1,

events/statechanged.rst

@@ -7,7 +7,7 @@ the number of seconds the folder spent in state ``from``. In the example
 below, the folder ``default`` was in state ``scanning`` for 0.198
 seconds and is now in state ``idle``.
 
-.. code:: json
+.. code-block:: json
 
     {
         "id": 8,

rest/db-browse-get.rst

@@ -12,7 +12,7 @@ tree we want to dwell down (0 based, defaults to unlimited depth)
 Optional parameter ``prefix`` defines a prefix within the tree where to
 start building the structure.
 
-.. code:: bash
+.. code-block:: bash
 
     $ curl -s http://localhost:8384/rest/db/browse?folder=default | json_pp
     {

rest/db-completion-get.rst

@@ -4,7 +4,7 @@ GET /rest/db/completion
 Returns the completion percentage (0 to 100) for a given device and
 folder.Takes ``device`` and ``folder`` parameters.
 
-.. code:: json
+.. code-block:: json
 
     {
       "completion": 0

rest/db-file-get.rst

@@ -4,7 +4,7 @@ GET /rest/db/file
 Returns most data available about a given file, including version and
 availability.
 
-.. code:: json
+.. code-block:: json
 
     {
       "availability": [

rest/db-ignores-get.rst

@@ -7,7 +7,7 @@ provides a compiled version of all included ignore patterns in the form
 of regular expressions. Excluded items in the ``patterns`` field have a
 nonstandard ``(?exclude)`` marker in front of the regular expression.
 
-.. code:: json
+.. code-block:: json
 
     {
       "ignore": [

rest/db-need-get.rst

@@ -4,7 +4,7 @@ GET /rest/db/need
 Takes one parameter, ``folder``, and returns lists of files which are
 needed by this device in order for it to become in sync.
 
-.. code:: bash
+.. code-block:: bash
 
     {
       # Files currently being downloaded

rest/db-prio-post.rst

@@ -3,7 +3,7 @@ POST /rest/db/prio
 
 Moves the file to the top of the download queue.
 
-.. code:: bash
+.. code-block:: bash
 
     curl -X POST http://127.0.0.1:8384/rest/db/prio?folder=default&file=foo/bar
 

rest/db-scan-post.rst

@@ -16,6 +16,6 @@ question.
 Returns status 200 and no content upon success, or status 500 and a
 plain text error if an error occurred during scanning.
 
-.. code:: bash
+.. code-block:: bash
 
     curl -X POST http://127.0.0.1:8384/rest/db/scan?folder=default&sub=foo/bar

rest/db-status-get.rst

@@ -5,7 +5,7 @@ Returns information about the current status of a folder.
 
 Parameters: ``folder``, the ID of a folder.
 
-.. code:: bash
+.. code-block:: bash
 
     {
       # latest version according to cluster:

rest/stats-device-get.rst

@@ -4,7 +4,7 @@ GET /rest/stats/device
 Returns general statistics about devices. Currently, only contains the
 time the device was last seen.
 
-.. code:: bash
+.. code-block:: bash
 
     $ curl -s http://localhost:8384/rest/stats/device | json
     {

rest/stats-folder-get.rst

@@ -4,7 +4,7 @@ GET /rest/stats/folder
 Returns general statistics about folders. Currently, only contains the
 last synced file.
 
-.. code:: bash
+.. code-block:: bash
 
     $ curl -s http://localhost:8384/rest/stats/folder | json
     {

rest/svc-deviceid-get.rst

@@ -6,7 +6,7 @@ Verifies and formats a device ID. Accepts all currently valid formats
 with trivial substitutions). Takes one parameter, ``id``, and returns
 either a valid device ID in modern format, or an error.
 
-.. code:: bash
+.. code-block:: bash
 
     $ curl -s http://localhost:8384/rest/svc/deviceid?id=1234 | json
     {

rest/svc-lang-get.rst

@@ -4,6 +4,6 @@ GET /rest/svc/lang
 Returns a list of canonicalized localization codes, as picked up from
 the ``Accept-Language`` header sent by the browser.
 
-.. code:: json
+.. code-block:: json
 
     ["sv_sv","sv","en_us","en"]

rest/svc-report-get.rst

@@ -3,7 +3,7 @@ GET /rest/svc/report
 
 Returns the data sent in the anonymous usage report.
 
-.. code:: json
+.. code-block:: json
 
     {
       "folderMaxFiles": 42106,

rest/system-config-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/config
 
 Returns the current configuration.
 
-.. code:: bash
+.. code-block:: bash
 
     {
      # etc

rest/system-config-insync-get.rst

@@ -4,7 +4,7 @@ GET /rest/system/config/insync
 Returns whether the config is in sync, i.e. whether the running
 configuration is the same as that on disk.
 
-.. code:: json
+.. code-block:: json
 
     {
       "configInSync": true

rest/system-connections-get.rst

@@ -4,7 +4,7 @@ GET /rest/system/connections
 Returns the list of current connections and some metadata associated
 with the connection/peer.
 
-.. code:: json
+.. code-block:: json
 
     {
       "connections": {

rest/system-discovery-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/discovery
 
 Returns the contents of the local discovery cache.
 
-.. code:: json
+.. code-block:: json
 
     {
       "LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q": [

rest/system-discovery-hint-post.rst

@@ -4,7 +4,7 @@ POST /rest/system/discovery/hint
 Post with the query parameters ``device`` and ``addr`` to add entries to
 the discovery cache.
 
-.. code:: bash
+.. code-block:: bash
 
     curl -X POST http://127.0.0.1:8384/rest/system/discovery/hint?device=LGFPDIT7SKNNJVJZA4FC7QNCRKCE753K72BW5QD2FOZ7FRFEP57Q\&addr=192.162.129.11:22000
     # Or with the X-API-Key header:

rest/system-error-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/error
 
 Returns the list of recent errors.
 
-.. code:: json
+.. code-block:: json
 
     {
       "errors": [

rest/system-ping-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/ping
 
 Returns a ``{"ping": "pong"}`` object.
 
-.. code:: json
+.. code-block:: json
 
     {
       "ping": "pong"

rest/system-status-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/status
 
 Returns information about current system status and resource usage.
 
-.. code:: json
+.. code-block:: json
 
     {
       "alloc": 30618136,

rest/system-upgrade-get.rst

@@ -4,7 +4,7 @@ GET /rest/system/upgrade
 Checks for a possible upgrade and returns an object describing the
 newest version and upgrade possibility.
 
-.. code:: json
+.. code-block:: json
 
     {
       "latest": "v0.10.27",

rest/system-version-get.rst

@@ -3,7 +3,7 @@ GET /rest/system/version
 
 Returns the current Syncthing version information.
 
-.. code:: json
+.. code-block:: json
 
     {
       "arch": "amd64",

users/autostart.rst

@@ -27,24 +27,24 @@ Start on Login
 Starting Syncthing on login, without a console window or browser opening
 on start, is relatively easy.
 
-1. Find the correct link of the Windows binary from the `Syncthing
+#. Find the correct link of the Windows binary from the `Syncthing
    website <https://github.com/syncthing/syncthing/releases>`__ (choose
    **amd64** if you have a 64-bit version of Windows)
-2. Extract the files in the folder (``syncthing-windows-*``) in the zip
+#. Extract the files in the folder (``syncthing-windows-*``) in the zip
    to the folder ``C:\syncthing``
-3. Go to the ``C:\syncthing`` folder, make a file named
+#. Go to the ``C:\syncthing`` folder, make a file named
    ``syncthing.bat``
-4. Right-click the file and choose **Edit**. The file should open in
+#. Right-click the file and choose **Edit**. The file should open in
    Notepad or your default text editor.
-5. Paste the following command into the file and save the changes:
+#. Paste the following command into the file and save the changes:
    ``start "Syncthing" syncthing.exe -no-console -no-browser``
-6. Right-click on ``syncthing.bat`` and press "Create Shortcut"
+#. Right-click on ``syncthing.bat`` and press "Create Shortcut"
-7. Right-click the shortcut file ``syncthing.bat - Shortcut`` and click
+#. Right-click the shortcut file ``syncthing.bat - Shortcut`` and click
    **Copy**
-8. Click **Start**, click **All Programs**, then click **Startup**.
+#. Click **Start**, click **All Programs**, then click **Startup**.
    Right-click on **Startup** then click **Open**.
    |Setup Screenshot|
-9. Paste the shortcut (right-click in the folder and choose **Paste**,
+#. Paste the shortcut (right-click in the folder and choose **Paste**,
    or press ``CTRL+V``)
 
 Syncthing will now automatically start the next time Windows boots. No
@@ -52,9 +52,9 @@ console or browser window will pop-up. Access the interface by browsing
 to http://localhost:8384/
 
 If you prefer slower indexing but a more responsive system during scans,
-copy the following command instead of the command in step 5:
+copy the following command instead of the command in step 5::
 
-``start "Syncthing" /low syncthing.exe -no-console -no-browser``
+    start "Syncthing" /low syncthing.exe -no-console -no-browser
 
 Run independent of user login
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -79,24 +79,24 @@ almost any end-user scenario. The only scenario where running Syncthing
 as a service makes sense is for (mostly) headless servers, administered
 by a sysadmin who knows enough to understand the security implications.
 
-1. Download and extract `nssm <http://nssm.cc/download>`__ to a folder
+#. Download and extract `nssm <http://nssm.cc/download>`__ to a folder
    where it can stay (e.g. *c:Files* or the Syncthing folder.
-2. run *nssm.exe install syncthing*
+#. run *nssm.exe install syncthing*
-3. Select ``syncthing.exe`` in the first tab and enter
+#. Select ``syncthing.exe`` in the first tab and enter
    ``-no-console -no-browser`` as Arguments
    |Configuration Screenshot|
-4. at the Details tab you can switch to *Automatic (Delayed Start)* to
+#. at the Details tab you can switch to *Automatic (Delayed Start)* to
    start it only some time after boot and speed up the boot process
    (optional)
-5. At the *Log On* tab you can enter a username and password for the
+#. At the *Log On* tab you can enter a username and password for the
    user to run Syncthing as. This user needs to have access to all the
    synced folders. Usually, you can leave it as the System account.
-6. At the Process Tab you can change the priority to low if you want a
+#. At the Process Tab you can change the priority to low if you want a
    more responsive system at the cost of longer sync time
-7. Click the *Install Service* Button
+#. Click the *Install Service* Button
-8. Start the service using the windows service manager, enter
+#. Start the service using the windows service manager, enter
    ``sc start syncthing`` in a console window or restart the PC.
-9. Connect to the Syncthing UI, enable HTTPS, and set a secure username
+#. Connect to the Syncthing UI, enable HTTPS, and set a secure username
    and password.
 
 Mac OS X
@@ -105,8 +105,8 @@ Mac OS X
 Using `homebrew <http://brew.sh>`__
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. ``brew install syncthing``
+#. ``brew install syncthing``
-2. Follow the info to autostart Syncthing using launchctl. At the moment
+#. Follow the info to autostart Syncthing using launchctl. At the moment
    this is done using this command:
    ``launchctl load ~/Library/LaunchAgents/homebrew.mxcl.syncthing.plist``.
 
@@ -116,18 +116,18 @@ Without homebrew
 Download Syncthing for Mac:
 https://github.com/syncthing/syncthing/releases/latest.
 
-1. Copy the syncthing binary (the file you would open to launch
+#. Copy the syncthing binary (the file you would open to launch
    Syncthing) in a directory called ``bin`` in your home directory. If
    "bin" does not exist, create it.
-2. Edit the ``syncthing.plist`` (located in /etc/macosx-launchd) in the
+#. Edit the ``syncthing.plist`` (located in /etc/macosx-launchd) in the
    two places that refer to your home directory; that is, replace
    /Users/jb with your actual home directory location.
-3. Copy the ``syncthing.plist`` file to ``~/Library/LaunchAgents``. If
+#. Copy the ``syncthing.plist`` file to ``~/Library/LaunchAgents``. If
    you have trouble finding this location select the "Go" menu in Finder
    and choose "Go to folder..." and then type
    ``~/Library/LaunchAgents``. Copying to ~/Library/LaunchAgents will
    require admin password in most cases.
-4. Log out and back in again. Or, if you do not want to log out, you can
+#. Log out and back in again. Or, if you do not want to log out, you can
    run this command in terminal:
    ``launchctl load ~/Library/LaunchAgents/syncthing.plist``
 
@@ -141,21 +141,18 @@ Linux
 Ubuntu like systems
 ~~~~~~~~~~~~~~~~~~~
 
-1. Click the dashboard (hit 'Win' button).
+#. Click the dashboard (hit 'Win' button).
-2. Open 'Startup Applications'.
+#. Open 'Startup Applications'.
-3. Click 'Add'.
+#. Click 'Add'.
-4. Fill out the form:
+#. Fill out the form:
 
    -  Name: Syncthing
-   -  Command: /path/to/syncthing/binary -no-browser
+   -  ``Command: /path/to/syncthing/binary -no-browser -home="/home/your\_user/.config/syncthing"``
-      -home="/home/your\_user/.config/syncthing"
 
 Supervisord
 ~~~~~~~~~~~
 
-Add following to your /etc/supervisord.conf.
+Add following to your ``/etc/supervisord.conf``::
-
-::
 
     [program:syncthing]
     command = /path/to/syncthing/binary -no-browser -home="/home/some_user/.config/syncthing"
@@ -174,7 +171,7 @@ ability to manage services under the user's control with a per-user
 systemd instance, enabling users to start, stop, enable, and disable
 their own units. Service files for system are provided by Syncthing and
 can be found in
-```etc/linux-systemd`` <https://github.com/syncthing/syncthing/tree/master/etc/linux-systemd>`__.
+`etc/linux-systemd <https://github.com/syncthing/syncthing/tree/master/etc/linux-systemd>`_.
 Several distros (including arch linux) ship these service files with the
 Syncthing package. If your distro provides a systemd service file for
 Syncthing you can skip step 2.
@@ -187,15 +184,13 @@ even if the Syncthing user has no active session. Since the system service
 keeps Syncthing running even without an active user session, it is intended to
 be used on a *server*.
 
-1. Create the user who should run the service, or choose an existing
+#. Create the user who should run the service, or choose an existing
    one.
-2. Copy the ``system/syncthing@.service`` file into the `load path of
+#. Copy the ``system/syncthing@.service`` file into the `load path of
    the system
    instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
-3. Enable and start the service. Append the Syncthing user after the
+#. Enable and start the service. Append the Syncthing user after the
-   ``@``:
+   ``@``::
-
-::
 
     systemctl enable syncthing@myuser.service
     systemctl start syncthing@myuser.service
@@ -208,24 +203,20 @@ Syncthing user has created a session (e.g. via the graphical login screen or
 ssh). Thus, the user service is intended to be used on a *(multiuser) desktop
 computer*. It avoids unnecessarily running Syncthing instances.
 
-1. Create the user who should run the service, or choose an existing
+#. Create the user who should run the service, or choose an existing
    one.
-2. Copy the ``user/syncthing.service`` file into the `load path of the
+#. Copy the ``user/syncthing.service`` file into the `load path of the
    user
    instance <http://www.freedesktop.org/software/systemd/man/systemd.unit.html#Unit%20Load%20Path>`__.
    To do this without root privileges you can use
    ``~/.config/systemd/user/``.
-3. Enable and start the service:
+#. Enable and start the service::
-
-::
 
     systemctl --user enable syncthing.service
     systemctl --user start syncthing.service
 
 To check if Syncthing runs properly you can use the ``status``
-subcommand:
+subcommand::
-
-::
 
     systemctl status syncthing@myuser.service
     systemctl --user status syncthing.service
@@ -234,9 +225,7 @@ Using the journal
 ^^^^^^^^^^^^^^^^^
 
 Systemd logs everything into the journal. You can easily access Syncthing
-log messages (``-e`` lets the pager jump to the very end):
+log messages (``-e`` lets the pager jump to the very end)::
-
-::
 
     journalctl -e -u syncthing@myuser.service
     journalctl -e --user-unit=syncthing.service
@@ -247,9 +236,7 @@ Debugging
 If you are asked on the bugtracker to start Syncthing with specific
 environment variables it will not work the easy way. Systemd isolates each
 service and it cannot access global environment variables. The solution is to
-add this variables to the service file instead. Just use:
+add this variables to the service file instead. Just use::
-
-::
 
     systemctl edit syncthing@myuser.service
     systemctl --user edit syncthing.service

users/config.rst

@@ -31,7 +31,7 @@ Config File Format
 
 The following is an example default configuration file:
 
-.. code:: xml
+.. code-block:: xml
 
     <configuration version="2">
         <folder id="default" directory="/Users/jb/Sync" ro="false" ignorePerms="false">

users/faq.rst

@@ -156,10 +156,10 @@ the iOS platform.
 Why does it use so much CPU?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-1. When new or changed files are detected, or Syncthing starts for the
+#. When new or changed files are detected, or Syncthing starts for the
    first time, your files are hashed using SHA-256.
 
-2. Data that is sent over the network is first compressed and then
+#. Data that is sent over the network is first compressed and then
    encrypted using AES-128. When receiving data, it must be decrypted
    and decompressed.
 
@@ -193,14 +193,14 @@ the GUI from the same machine. Change the ``GUI listen address`` through
 the web UI from ``127.0.0.1:8384`` to ``0.0.0.0:8384`` or change the
 config.xml:
 
-.. code:: xml
+.. code-block:: xml
 
     <gui enabled="true" tls="false">
       <address>127.0.0.1:8384</address>
 
 to
 
-.. code:: xml
+.. code-block:: xml
 
     <gui enabled="true" tls="false">
       <address>0.0.0.0:8384</address>
@@ -212,7 +212,7 @@ If both your computers are Unixy (Linux, Mac, etc) You can also leave
 the GUI settings at default and use an ssh port forward to access it.
 For example,
 
-.. code:: bash
+.. code-block:: bash
 
     $ ssh -L 9090:127.0.0.1:8384 user@othercomputer.example.com