chore: clarify database resetting options (#1013)

The `--reset-deltas` and `--reset-database` options were removed in
Syncthing v2. Fix leftover references and in the process, document the
current `syncthing debug ...` subcommand group, where `reset-database`
now lives.

* Stop referring to removed --reset-deltas option.

* Describe debug subcommand similar to the cli hierarchy.

Clarify that "cli debug" commands do not require Syncthing to be
stopped, while in fact removing the database completely should not be
done while it is running.  Point to the corresponding API endpoint
/rest/system/reset for more granular DB reset functionality.

* Add a label for the reset-database subcommand.

Currently not used as a target anywhere, but might prove useful for a
future FAQ.

Add the includes top-level directory to the exclusion list for Sphinx.
Documents in there are always used via an include:: directive, so
processing them as (unreachable) standalone documents leads to
duplicate label warnings.

* Fix obsolete reference to --reset-database option.

The cautionary note was removed in v2 together with the whole option.
Resurrect the text from the old option doc.

Signed-off-by: André Colomb <src@andre.colomb.de>

Author: acolomb

conf.py

@@ -92,7 +92,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ['_build', '_syncthing', 'draft', 'README.rst', 'users/faq-parts']
+exclude_patterns = ['_build', '_syncthing', 'draft', 'README.rst', 'users/faq-parts', 'includes']
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

includes/cli-commands.rst

@@ -24,8 +24,7 @@ errors
 
 debug
     Various tools to aid in diagnosing problems or collection information for
-    bug reports.  Some of these commands access the database directly and can
-    therefore only work when Syncthing is not running.
+    bug reports.
 
 ``-`` (a single dash)
     Reads subsequent commands from the standard input stream, without needing to

includes/debug-commands.rst

@@ -0,0 +1,16 @@
+.. _reset-database:
+
+debug reset-database
+    Reset the database, forcing a full rescan and resync.  **Must only be used
+    when Syncthing is not running.**  More granular reset operations are
+    available on the REST API while Syncthing is running:
+    :doc:`../rest/system-reset-post`
+
+debug database-statistics
+    Display database size statistics.
+
+debug database-counts
+    Display database folder counts.
+
+debug database-file
+    Display database file metadata.

rest/system-reset-post.rst

@@ -10,5 +10,7 @@ information for that folder will be erased:
 
         curl -X POST -H "X-API-Key: abc123" http://localhost:8384/rest/system/reset?folder=ab1c2-def3g
 
-**Caution**: See :option:`--reset-database` for ``.stfolder`` creation
-side-effect and caution regarding mountpoints.
+Creates ``.stfolder`` folders in each sync folder if they do not already exist.
+**Caution**: Ensure that all sync folders which are mountpoints are already
+mounted.  Inconsistent versions may result if the mountpoint is later mounted
+and contains older versions.

users/config.rst

@@ -1337,11 +1337,10 @@ The ``options`` element contains all other global configuration options.
 
 .. option:: options.sendFullIndexOnUpgrade
 
-    Controls whether all index data is resent when an upgrade has happened,
-    equivalent to starting Syncthing with :option:`--reset-deltas`.  This used
-    to be the default behavior in older versions, but is mainly useful as a
-    troubleshooting step and causes high database churn. The default is now
-    ``false``.
+    Controls whether all index data is resent when an upgrade has happened.
+    This used to be the default behavior in older versions, but is mainly useful
+    as a troubleshooting step and causes high database churn.  The default is
+    now ``false``.
 
 .. option:: options.featureFlag
     :aliases: options.featureFlags

users/syncthing.rst

@@ -323,6 +323,14 @@ saves the hassle of handling HTTP connections and API authentication.
 
 .. include:: ../includes/cli-commands.rst
 
+For troubleshooting issues, the ``debug`` subcommand provides some commonly
+needed actions for data analysis and repair.  Some of these commands access the
+database directly and can therefore only work when Syncthing is not running.
+Not to be confused with the ``cli debug`` subcommand group, which works via the
+REST API.
+
+.. include:: ../includes/debug-commands.rst
+
 Proxies
 -------