diff --git a/docs/index.rst b/docs/index.rst index 92d569c..4203bf4 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,7 +19,7 @@ Table of Contents config keyring supported - support + problems changelog vdir license diff --git a/docs/problems.rst b/docs/problems.rst new file mode 100644 index 0000000..8bb5d1d --- /dev/null +++ b/docs/problems.rst @@ -0,0 +1,67 @@ +========================== +Support and known Problems +========================== + +For any unanswered questions or problems, `open an issue on GitHub +`_ or `contact me directly +`_. + +Error messages +-------------- + +- **[Errno 185090050] _ssl.c:343: error:0B084002:x509 certificate + routines:X509_load_cert_crl_file:system lib** + + vdirsyncer cannot find the path to your certificate bundle, you need to + supply it as a parameter to ``verify`` in storage configuration, e.g.:: + + verify = /usr/share/ca-certificates/cacert.org/cacert.org_root.crt + +- **ImportError: No module named packages.urllib3.poolmanager** + + This happens if the requests package was installed via Debian's package + manager, see :gh:`82`. You have two options for solving this problem: + + - Upgrade your installation of the Debian requests package to at least + version ``2.4.3-1``. + + - Install vdirsyncer in a virtualenv, see :ref:`manual_installation`. + + +.. _manual-installation: + +Manual installation +------------------- + +If your distribution doesn't provide a package for vdirsyncer, you still can +use Python's package manager "pip". First, you'll have to check that a +compatible version of Python (2.7+ or 3.3+) and the corresponding pip package +are installed. On Linux systems, using the distro's package manager is the best +way to do this. + +The easiest way to install vdirsyncer at this point would be to run:: + + pip install --user vdirsyncer + +This method has a major flaw though: Pip doesn't keep track of which files it +installs. Vdirsyncer's files would be located somewhere in +``~/.local/lib/python*``, but you can't possibly know which packages were +installed as dependencies of vdirsyncer and which ones were not, should you +decide to uninstall it. In other words, using pip that way would pollute your +home directory. + +But there is a way to install Python software without scattering stuff across +your filesystem: virtualenv_. There are a lot of resources on how to use it, +the simplest possible way would something like:: + + virtualenv ~/vdirsyncer_env + ~/vdirsyncer_env/bin/pip install vdirsyncer + alias vdirsyncer="~/vdirsyncer_env/bin/vdirsyncer + +You'll have to put the last line into your ``.bashrc`` or ``.bash_profile``. +The main advantage is that you can delete the ``~/vdirsyncer_env`` folder to +uninstall vdirsyncer. Also, pipsi_ is a relatively new tool which tries to +automate this process in a end-user friendly way. + +.. _virtualenv: https://virtualenv.readthedocs.org/ +.. _pipsi: https://github.com/mitsuhiko/pipsi diff --git a/docs/support.rst b/docs/support.rst deleted file mode 100644 index 262d22b..0000000 --- a/docs/support.rst +++ /dev/null @@ -1,18 +0,0 @@ -======= -Support -======= - -For any questions left unanswered by the documentation, `open an issue on -GitHub `_ or `contact me -directly `_. - -Troubleshooting -=============== - -- **[Errno 185090050] _ssl.c:343: error:0B084002:x509 certificate - routines:X509_load_cert_crl_file:system lib** - - vdirsyncer cannot find the path to your certificate bundle, you need to - supply it as a parameter to ``verify`` in your config file, e.g.:: - - verify = /usr/share/ca-certificates/cacert.org/cacert.org_root.crt diff --git a/docs/tutorial.rst b/docs/tutorial.rst index 1570155..a1f9c58 100644 --- a/docs/tutorial.rst +++ b/docs/tutorial.rst @@ -5,29 +5,15 @@ Tutorial Installation ============ -Vdirsyncer requires Python 2.7+ or 3.3+. - Unless you want to contribute to vdirsyncer, you should use the packages from your distribution: - `AUR package for ArchLinux `_ - `pkgsrc `_ -If your distribution doesn't provide a package for vdirsyncer, you still can -use Python's package manager "pip". You'll have to check that a compatible -version of Python is installed (see above), and then run:: - - pip install --user vdirsyncer - -This will install vdirsyncer and its dependencies into your home directory, -presumably into ``~/local/lib/pythonX.X/``, and an executable under -``~/.local/bin/``. You then can uninstall vdirsyncer with ``pip uninstall -vdirsyncer``, but this will leave vdirsyncer's dependencies on your system, -whose files you'll have to remove manually from the mentioned directories. You -could check out pipsi_, but that one is a quite new tool. You should always -prefer the packages of your distribution over this method. - -.. _pipsi: https://github.com/mitsuhiko/pipsi +If there is no package for your distribution, you'll need to :ref:`install +vdirsyncer manually `. There is an easy command to +copy-and-paste for this as well, but you should be aware of its consequences. Configuration =============