docs: clean up .rst and references

This uses Read-The-Docs (sphinx/docutils) references exclusively, but adds a
README.md for GitHub viewers to remind them that the links there won't
work (closes ticket:2835).

It also fixes all the dangling references and other Sphinx warnings.

The "Preparation" section of docs/magic-folder-howto.rst was removed, since
this feature has since been merged to trunk.

docs/INSTALL.rst

@@ -1,18 +1,22 @@
 .. -*- coding: utf-8-with-signature-unix; fill-column: 77 -*-
 
+..
+    note: if you aren't reading the rendered form of these docs at
+    http://tahoe-lafs.readthedocs.io/en/latest/ , then be aware that any
+    ":doc:" links refer to other files in this docs/ directory
+
 *********************
 Installing Tahoe-LAFS
 *********************
 
 Welcome to `the Tahoe-LAFS project`_, a secure, decentralized, fault-tolerant
-storage system. See `about.rst`_ for an overview of the architecture and
+storage system. See :doc:`about` for an overview of the architecture and
 security properties of the system.
 
 This procedure should work on Windows, Mac, OpenSolaris, and too many flavors
 of Linux and of BSD to list.
 
 .. _the Tahoe-LAFS project: https://tahoe-lafs.org
-.. _about.rst: about.rst
 
 First: In Case Of Trouble
 =========================
@@ -31,11 +35,11 @@ Pre-Packaged Versions
 
 You may not need to build Tahoe at all.
 
-If you are on Windows, please see `windows.rst`_ for platform-specific
+If you are on Windows, please see :doc:`windows` for platform-specific
 instructions.
 
 If you are on a Mac, you can either follow these instructions, or use the
-pre-packaged bundle described in `OS-X.rst`_. The Tahoe project hosts
+pre-packaged bundle described in :doc:`OS-X`. The Tahoe project hosts
 pre-compiled "wheels" for all dependencies, so use the ``--find-links=``
 option described below to avoid needing a compiler.
 
@@ -44,8 +48,6 @@ can ``apt-get install tahoe-lafs``. See `OSPackages`_ for other
 platforms.
 
 .. _OSPackages: https://tahoe-lafs.org/trac/tahoe-lafs/wiki/OSPackages
-.. _windows.rst: windows.rst
-.. _OS-X.rst: OS-X.rst
 
 
 Preliminaries
@@ -303,6 +305,4 @@ Using Tahoe-LAFS
 
 Now you are ready to deploy a decentralized filesystem. You will use the
 ``tahoe`` executable to create, configure, and launch your Tahoe-LAFS nodes.
-See `running.rst`_ for instructions on how to do that.
+See :doc:`running` for instructions on how to do that.
-
-.. _running.rst: running.rst

docs/README.md

@@ -0,0 +1,7 @@
+
+Note: http://tahoe-lafs.readthedocs.io/en/latest/ is the preferred place to
+read this documentation (GitHub doesn't render cross-document links or
+images). If you're reading this on https://github.com/tahoe-lafs/tahoe-lafs ,
+or from a checked-out source tree, then either run `tox -e docs` and open
+_build/html/index.html in your browser, or view the pre-rendered trunk copy
+at http://tahoe-lafs.readthedocs.io/en/latest/

docs/about.rst

@@ -132,6 +132,12 @@ To use Tahoe-LAFS, please see :doc:`INSTALL`.
 License
 =======
 
-Tahoe-LAFS is an open-source project; please see README.rst_ for details.
+Tahoe-LAFS is an open-source project; please see the `top-level README`_ for
+details.
+
+..
+   this is really ../README.rst, but it's not included in the Sphinx build so
+   we can't link to it normally
+
+.. _top-level README: https://github.com/tahoe-lafs/tahoe-lafs/blob/master/README.rst
 
-.. _README.rst: ../README.rst

docs/anonymity-configuration.rst

@@ -6,7 +6,6 @@ Using Tahoe-LAFS with an anonymizing network: Tor, I2P
 
 #. `Overview`_
 #. `Use cases`_
-#. `Unresolved tickets`_
 
 #. `Software Dependencies`_
 
@@ -147,10 +146,10 @@ extras enabled::
 Connection configuration
 ========================
 
-See :ref:`configuration` "Client Configuration" for a description of the
+See :ref:`Connection Management` for a description of the ``[tor]`` and
-``[tor]`` and ``[i2p]`` sections of ``tahoe.cfg``. These control how the
+``[i2p]`` sections of ``tahoe.cfg``. These control how the Tahoe client will
-Tahoe client will connect to a Tor/I2P daemon, and thus make connections to
+connect to a Tor/I2P daemon, and thus make connections to Tor/I2P -based
-Tor/I2P -based servers.
+servers.
 
 The ``[tor]`` and ``[i2p]`` sections only need to be modified to use unusual
 configurations, or to enable automatic server setup.

docs/configuration.rst

@@ -365,6 +365,8 @@ set the ``tub.location`` option described below.
       rather than being set to ``tor`` or ``disabled``
 
 
+.. _Connection Management:
+
 Connection Management
 =====================
 
@@ -558,6 +560,7 @@ on port 7656. This is the default SAM port for the ``i2p`` daemon.
     be used.
 
 
+.. _Client Configuration:
 
 Client Configuration
 ====================

docs/frontends/magic-folder.rst

@@ -6,7 +6,7 @@ Tahoe-LAFS Magic Folder Frontend
 
 1.  `Introduction`_
 2.  `Configuration`_
-3.  `Known Issues and Limitations`_
+3.  `Known Issues and Limitations With Magic-Folder`_
 
 
 Introduction
@@ -40,13 +40,14 @@ Configuration
 
 The Magic Folder frontend runs as part of a gateway node. To set it up, you
 must use the tahoe magic-folder CLI. For detailed information see our
-`Magic-Folder CLI design documentation`_. For a given Magic-Folder collective
+:doc:`Magic-Folder CLI design
-directory you need to run the ``tahoe magic-folder create`` command. After
+documentation<../proposed/magic-folder/user-interface-design>`. For a
-that the ``tahoe magic-folder invite`` command must used to generate an
+given Magic-Folder collective directory you need to run the ``tahoe
-*invite code* for each member of the magic-folder collective. A confidential,
+magic-folder create`` command. After that the ``tahoe magic-folder invite``
-authenticated communications channel should be used to transmit the invite code
+command must used to generate an *invite code* for each member of the
-to each member, who will be joining using the ``tahoe magic-folder join``
+magic-folder collective. A confidential, authenticated communications channel
-command.
+should be used to transmit the invite code to each member, who will be
+joining using the ``tahoe magic-folder join`` command.
 
 These settings are persisted in the ``[magic_folder]`` section of the
 gateway's ``tahoe.cfg`` file.
@@ -81,8 +82,10 @@ page and the node :doc:`log<../logging>` may be helpful to determine the
 cause of any failures.
 
 
-Known Issues and Limitations
+.. _Known Issues in Magic-Folder:
-============================
+
+Known Issues and Limitations With Magic-Folder
+==============================================
 
 This feature only works on Linux and Windows. There is a ticket to add
 support for Mac OS X and BSD-based systems (`#1432`_).
@@ -143,6 +146,3 @@ On Windows, when a node has Magic Folder enabled, it is unresponsive to Ctrl-C
 .. _`#2218`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2218
 .. _`#2219`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2219
 .. _`#2440`: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2440
-
-.. _`garbage collection`: ../garbage-collection.rst
-.. _`Magic-Folder CLI design documentation`: ../proposed/magic-folder/user-interface-design.rst

docs/index.rst

@@ -19,7 +19,7 @@ Contents:
    frontends/CLI
    frontends/webapi
    frontends/FTP-and-SFTP
-   frontends/drop-upload
+   frontends/magic-folder
    frontends/download-status
 
    known_issues
@@ -31,8 +31,10 @@ Contents:
 
    backdoors
    donations
+   expenses
    cautions
    write_coordination
+   magic-folder-howto
    backupdb
 
    anonymity-configuration

docs/key-value-store.rst

@@ -26,7 +26,7 @@ options:
       This is spelled "`GET /uri/$FILECAP`_" in the API. "$FILECAP" is the
       key.
 
-   For details, see "immutable files" in `performance.rst`_, but in summary:
+   For details, see "immutable files" in :doc:`performance`, but in summary:
    the performance is not great but not bad.
 
    That document doesn't mention that if the size of the A-byte mutable file
@@ -57,7 +57,7 @@ options:
       change what value you get when you read) depends on the type of the
       key.
 
-   Again, for details, see "mutable files" in `performance.rst`_ (and
+   Again, for details, see "mutable files" in :doc:`performance` (and
    `these tickets`_ about how that doc is incomplete), but in summary, the
    performance of the create() operation is *terrible*! (It involves
    generating a 2048-bit RSA key pair.) The performance of the set and get
@@ -71,7 +71,7 @@ options:
 
       This is spelled "`POST /uri?t=mkdir`_".
 
-      `performance.rst`_ does not mention directories (`#2228`_), but in order
+      :doc:`performance` does not mention directories (`#2228`_), but in order
       to understand the performance of directories you have to understand how
       they are implemented. Mkdir creates a new mutable file, exactly the
       same, and with exactly the same performance, as the "create() mutable"
@@ -134,8 +134,6 @@ sqlite db in a Tahoe-LAFS mutable". ☺
 
 .. _PUT /uri?format=mdmf: https://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/frontends/webapi.rst#writing-uploading-a-file
 
-.. _performance.rst: https://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/performance.rst
-
 .. _#2226: https://tahoe-lafs.org/trac/tahoe-lafs/ticket/2226
 
 .. _these tickets: https://tahoe-lafs.org/trac/tahoe-lafs/query?status=assigned&status=new&status=reopened&keywords=~doc&description=~performance.rst&col=id&col=summary&col=status&col=owner&col=type&col=priority&col=milestone&order=priority

docs/magic-folder-howto.rst

@@ -2,95 +2,27 @@
 Magic Folder Set-up Howto
 =========================
 
-1.  `This document`_
+#.  `This document`_
-2.  `Preparation`_
+#.  `Setting up a local test grid`_
-3.  `Setting up a local test grid`_
+#.  `Setting up Magic Folder`_
-4.  `Setting up Magic Folder`_
+#.  `Testing`_
-5.  `Testing`_
 
 
 This document
 =============
 
-This is preliminary documentation of how to set up the
+This is preliminary documentation of how to set up Magic Folder using a test
-Magic Folder pre-release using a test grid on a single Linux
+grid on a single Linux or Windows machine, with two clients and one server.
-or Windows machine, with two clients and one server. It is
+It is aimed at a fairly technical audience.
-aimed at a fairly technical audience.
 
 For an introduction to Magic Folder and how to configure it
-more generally, see `docs/frontends/magic-folder.rst`_.
+more generally, see :doc:`frontends/magic-folder`.
 
 It it possible to adapt these instructions to run the nodes on
 different machines, to synchronize between three or more clients,
 to mix Windows and Linux clients, and to use multiple servers
 (if the Tahoe-LAFS encoding parameters are changed).
 
-.. _`docs/frontends/magic-folder.rst`: ../docs/frontends/magic-folder.rst
-
-
-Preparation
-===========
-
-Linux
------
-
-Install ``git`` from your distribution's package manager.
-Then run these commands::
-
-  git clone -b 2438.magic-folder-stable.8 https://github.com/tahoe-lafs/tahoe-lafs.git
-  cd tahoe-lafs
-  python setup.py test
-
-The test suite usually takes about 15 minutes to run.
-Note that it is normal for some tests to be skipped.
-In the current branch, the Magic Folder tests produce
-considerable debugging output.
-
-If you see an error like ``fatal error: Python.h: No such file or directory``
-while compiling the dependencies, you need the Python development headers. If
-you are on a Debian or Ubuntu system, you can install them with ``sudo
-apt-get install python-dev``. On RedHat/Fedora, install ``python-devel``.
-
-
-Windows
--------
-
-Windows 7 or above is required.
-
-For 64-bit Windows:
-
-* Install Python 2.7 from
-  https://www.python.org/ftp/python/2.7/python-2.7.amd64.msi
-* Install pywin32 from
-  https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win-amd64-py2.7.exe
-* Install git from
-  https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-64-bit.exe
-
-For 32-bit Windows:
-
-* Install Python 2.7 from
-  https://www.python.org/ftp/python/2.7/python-2.7.msi
-* Install pywin32 from
-  https://tahoe-lafs.org/source/tahoe-lafs/deps/windows/pywin32-219.win32-py2.7.exe
-* Install git from
-  https://github.com/git-for-windows/git/releases/download/v2.6.2.windows.1/Git-2.6.2-32-bit.exe
-
-Then (for any version) run these commands in a Command Prompt::
-
-  git clone -b 2438.magic-folder-stable.5 https://github.com/tahoe-lafs/tahoe-lafs.git
-  cd tahoe-lafs
-  python setup.py build
-
-Open a new Command Prompt with the same current directory,
-then run::
-
-  bin\tahoe --version-and-path
-
-It is normal for this command to print warnings and debugging output
-on some systems. ``python setup.py test`` can also be run, but there
-are some known sources of nondeterministic errors in tests on Windows
-that are unrelated to Magic Folder.
-
 
 Setting up a local test grid
 ============================
@@ -222,8 +154,8 @@ Note that when a file is deleted, the corresponding file in the
 other directory will be renamed to a filename ending in ``.backup``.
 Deleting a directory will have no effect.
 
-For other known issues and limitations, see
+For other known issues and limitations, see :ref:`Known Issues in
-https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.8/docs/frontends/magic-folder.rst#known-issues-and-limitations
+Magic-Folder`.
 
 As mentioned earlier, it is also possible to run the nodes on
 different machines, to synchronize between three or more clients,

docs/proposed/index.rst

@@ -17,3 +17,4 @@ index only lists the files that are in .rst format.
    magic-folder/filesystem-integration
    magic-folder/remote-to-local-sync
    magic-folder/user-interface-design
+   magic-folder/multi-party-conflict-detection

docs/proposed/magic-folder/multi-party-conflict-detection.rst

@@ -44,8 +44,8 @@ The desired behaviour for initially classifying overwrites and conflicts is as f
 * if, in the same situation, V' does not follow V, then the write of the new version should be
   classified as a conflict.
 
-The existing `Magic Folder design for remote-to-local sync`_ defines when an initial overwrite
+The existing :doc:`remote-to-local-sync` document defines when an initial
-should be reclassified as a conflict.
+overwrite should be reclassified as a conflict.
 
 The above definitions completely specify the desired solution of the false
 conflict behaviour described in the `ticket comment`_. However, they do not give
@@ -55,8 +55,6 @@ Tahoe-LAFS file store of the metadata needed to compute it.
 We will consider two alternative designs, proposed by Leif Ryge and
 Zooko Wilcox-O'Hearn, that aim to fill this gap.
 
-.. _`Magic Folder design for remote-to-local sync`: remote-to-local-sync.rst
-
 
 
 Leif's Proposal: Magic-Folder "single-file" snapshot design

docs/specifications/backends/raic.rst

@@ -404,4 +404,4 @@ References
 
 ¹¹ “Performance costs for some common operations” tahoe-lafs.org (2012)
 
-    https://tahoe-lafs.org/trac/tahoe-lafs/browser/trunk/docs/performance.rst
+    :doc:`../../performance`