From 91047bf828e0fd3cf1cfa674963234851de4211d Mon Sep 17 00:00:00 2001 From: Brian Warner Date: Mon, 12 Dec 2016 13:48:13 -0800 Subject: [PATCH] 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 | 18 ++-- docs/README.md | 7 ++ docs/about.rst | 10 ++- docs/anonymity-configuration.rst | 9 +- docs/configuration.rst | 3 + docs/expenses.rst | 2 +- docs/frontends/magic-folder.rst | 26 +++--- docs/index.rst | 4 +- docs/key-value-store.rst | 8 +- docs/magic-folder-howto.rst | 88 +++---------------- docs/proposed/index.rst | 1 + .../multi-party-conflict-detection.rst | 6 +- docs/specifications/backends/raic.rst | 2 +- 13 files changed, 65 insertions(+), 119 deletions(-) create mode 100644 docs/README.md diff --git a/docs/INSTALL.rst b/docs/INSTALL.rst index bd1f0df12..02ea0ca06 100644 --- a/docs/INSTALL.rst +++ b/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. - -.. _running.rst: running.rst +See :doc:`running` for instructions on how to do that. diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..87c9583d9 --- /dev/null +++ b/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/ diff --git a/docs/about.rst b/docs/about.rst index 0e1cf5cd6..fe820c2b1 100644 --- a/docs/about.rst +++ b/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 diff --git a/docs/anonymity-configuration.rst b/docs/anonymity-configuration.rst index 531474630..c8266c849 100644 --- a/docs/anonymity-configuration.rst +++ b/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 -``[tor]`` and ``[i2p]`` sections of ``tahoe.cfg``. These control how the -Tahoe client will connect to a Tor/I2P daemon, and thus make connections to -Tor/I2P -based servers. +See :ref:`Connection Management` for a description of the ``[tor]`` and +``[i2p]`` sections of ``tahoe.cfg``. These control how the Tahoe client will +connect to a Tor/I2P daemon, and thus make connections to Tor/I2P -based +servers. The ``[tor]`` and ``[i2p]`` sections only need to be modified to use unusual configurations, or to enable automatic server setup. diff --git a/docs/configuration.rst b/docs/configuration.rst index 6e10dda42..978680dd9 100644 --- a/docs/configuration.rst +++ b/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 ==================== diff --git a/docs/expenses.rst b/docs/expenses.rst index d83e9eeca..fbb4293ef 100644 --- a/docs/expenses.rst +++ b/docs/expenses.rst @@ -122,7 +122,7 @@ developer summit. * Address: 1DskmM8uCvmvTKjPbeDgfmVsGifZCmxouG * 2016 Summit (Nov 8-9, San Francisco) -* Rental of the Mechanics Institute Library "Board Room": $300/day *2 +* Rental of the Mechanics Institute Library "Board Room": $300/day*2 * Team Dinner (Cha Cha Cha): $164.49 * Team Dinner (Rasoi): $255.34 * -- total: $1019.83 diff --git a/docs/frontends/magic-folder.rst b/docs/frontends/magic-folder.rst index 1284a1572..694958563 100644 --- a/docs/frontends/magic-folder.rst +++ b/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 -directory you need to run the ``tahoe magic-folder create`` command. After -that the ``tahoe magic-folder invite`` command must used to generate an -*invite code* for each member of the magic-folder collective. A confidential, -authenticated communications channel should be used to transmit the invite code -to each member, who will be joining using the ``tahoe magic-folder join`` -command. +:doc:`Magic-Folder CLI design +documentation<../proposed/magic-folder/user-interface-design>`. For a +given Magic-Folder collective directory you need to run the ``tahoe +magic-folder create`` command. After that the ``tahoe magic-folder invite`` +command must used to generate an *invite code* for each member of the +magic-folder collective. A confidential, authenticated communications channel +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 diff --git a/docs/index.rst b/docs/index.rst index ed160b221..aafd7cba9 100644 --- a/docs/index.rst +++ b/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 diff --git a/docs/key-value-store.rst b/docs/key-value-store.rst index db3bea579..6f4774492 100644 --- a/docs/key-value-store.rst +++ b/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 diff --git a/docs/magic-folder-howto.rst b/docs/magic-folder-howto.rst index 813f53b1f..655cdb190 100644 --- a/docs/magic-folder-howto.rst +++ b/docs/magic-folder-howto.rst @@ -2,95 +2,27 @@ Magic Folder Set-up Howto ========================= -1. `This document`_ -2. `Preparation`_ -3. `Setting up a local test grid`_ -4. `Setting up Magic Folder`_ -5. `Testing`_ +#. `This document`_ +#. `Setting up a local test grid`_ +#. `Setting up Magic Folder`_ +#. `Testing`_ This document ============= -This is preliminary documentation of how to set up the -Magic Folder pre-release using a test grid on a single Linux -or Windows machine, with two clients and one server. It is -aimed at a fairly technical audience. +This is preliminary documentation of how to set up Magic Folder using a test +grid on a single Linux or Windows machine, with two clients and one server. +It is 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 -https://github.com/tahoe-lafs/tahoe-lafs/blob/2438.magic-folder-stable.8/docs/frontends/magic-folder.rst#known-issues-and-limitations +For other known issues and limitations, see :ref:`Known Issues in +Magic-Folder`. As mentioned earlier, it is also possible to run the nodes on different machines, to synchronize between three or more clients, diff --git a/docs/proposed/index.rst b/docs/proposed/index.rst index a53e59849..3211b317f 100644 --- a/docs/proposed/index.rst +++ b/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 diff --git a/docs/proposed/magic-folder/multi-party-conflict-detection.rst b/docs/proposed/magic-folder/multi-party-conflict-detection.rst index d99b62c15..fb1ae8339 100644 --- a/docs/proposed/magic-folder/multi-party-conflict-detection.rst +++ b/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 -should be reclassified as a conflict. +The existing :doc:`remote-to-local-sync` document defines when an initial +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 diff --git a/docs/specifications/backends/raic.rst b/docs/specifications/backends/raic.rst index ed88307ec..cb7a3081f 100644 --- a/docs/specifications/backends/raic.rst +++ b/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`