ExternalVendorCode/tahoe-lafs
1
0
Fork 0
mirror of https://github.com/tahoe-lafs/tahoe-lafs.git synced 2025-01-24 21:36:47 +00:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity

docs: clean up .rst and references

Browse Source 
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.
This commit is contained in:
Brian Warner 2016-12-12 13:48:13 -08:00
parent 1bb62d843f
commit 91047bf828
13 changed files with 65 additions and 119 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

18
docs/INSTALL.rst
View File

@ -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.

7
docs/README.md Normal file
View File

@ -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/

10
docs/about.rst
View File

@ -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

9
docs/anonymity-configuration.rst
View File

@ -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.

3
docs/configuration.rst
View File

@ -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
====================

2
docs/expenses.rst
View File

@ -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

26
docs/frontends/magic-folder.rst
View File

@ -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

4
docs/index.rst
View File

@ -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

8
docs/key-value-store.rst
View File

@ -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

88
docs/magic-folder-howto.rst
View File

@ -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,

1
docs/proposed/index.rst
View File

@ -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

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

@ -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

2
docs/specifications/backends/raic.rst
View File

@ -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`