diff options
| author | kali <kali@leap.se> | 2013-05-03 02:59:22 +0900 |
|---|---|---|
| committer | kali <kali@leap.se> | 2013-05-11 21:59:58 +0900 |
| commit | 2dae2703fb8c2ae7e721ce83020c0dd10ff9ca33 (patch) | |
| tree | 280cb8751c56d43769fb15ead4fb4476960ae06c /docs | |
| parent | c85894efdbd6f65eb2b0c2edfc216827c192c1d1 (diff) | |
updated documentation
* documentation reviewed after rewrite, ready for 0.2.1
* updated docstrings format to fit sphinx autodoc
Diffstat (limited to 'docs')
32 files changed, 1889 insertions, 0 deletions
diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 00000000..16aa258b --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,153 @@ +# Makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +PAPER = +BUILDDIR = _build + +# Internal variables. +PAPEROPT_a4 = -D latex_paper_size=a4 +PAPEROPT_letter = -D latex_paper_size=letter +ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . +# the i18n builder cannot share the environment and doctrees with the others +I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . + +.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext + +help: + @echo "Please use \`make <target>' where <target> is one of" + @echo " html to make standalone HTML files" + @echo " dirhtml to make HTML files named index.html in directories" + @echo " singlehtml to make a single large HTML file" + @echo " pickle to make pickle files" + @echo " json to make JSON files" + @echo " htmlhelp to make HTML files and a HTML help project" + @echo " qthelp to make HTML files and a qthelp project" + @echo " devhelp to make HTML files and a Devhelp project" + @echo " epub to make an epub" + @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" + @echo " latexpdf to make LaTeX files and run them through pdflatex" + @echo " text to make text files" + @echo " man to make manual pages" + @echo " texinfo to make Texinfo files" + @echo " info to make Texinfo files and run them through makeinfo" + @echo " gettext to make PO message catalogs" + @echo " changes to make an overview of all changed/added/deprecated items" + @echo " linkcheck to check all external links for integrity" + @echo " doctest to run all doctests embedded in the documentation (if enabled)" + +clean: + -rm -rf $(BUILDDIR)/* + +html: + $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +dirhtml: + $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml + @echo + @echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml." + +singlehtml: + $(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml + @echo + @echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml." + +pickle: + $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle + @echo + @echo "Build finished; now you can process the pickle files." + +json: + $(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json + @echo + @echo "Build finished; now you can process the JSON files." + +htmlhelp: + $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp + @echo + @echo "Build finished; now you can run HTML Help Workshop with the" \ + ".hhp project file in $(BUILDDIR)/htmlhelp." + +qthelp: + $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp + @echo + @echo "Build finished; now you can run "qcollectiongenerator" with the" \ + ".qhcp project file in $(BUILDDIR)/qthelp, like this:" + @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/LEAP.qhcp" + @echo "To view the help file:" + @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/LEAP.qhc" + +devhelp: + $(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp + @echo + @echo "Build finished." + @echo "To view the help file:" + @echo "# mkdir -p $$HOME/.local/share/devhelp/LEAP" + @echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/LEAP" + @echo "# devhelp" + +epub: + $(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub + @echo + @echo "Build finished. The epub file is in $(BUILDDIR)/epub." + +latex: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo + @echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex." + @echo "Run \`make' in that directory to run these through (pdf)latex" \ + "(use \`make latexpdf' here to do that automatically)." + +latexpdf: + $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex + @echo "Running LaTeX files through pdflatex..." + $(MAKE) -C $(BUILDDIR)/latex all-pdf + @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex." + +text: + $(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text + @echo + @echo "Build finished. The text files are in $(BUILDDIR)/text." + +man: + $(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man + @echo + @echo "Build finished. The manual pages are in $(BUILDDIR)/man." + +texinfo: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo + @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo." + @echo "Run \`make' in that directory to run these through makeinfo" \ + "(use \`make info' here to do that automatically)." + +info: + $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo + @echo "Running Texinfo files through makeinfo..." + make -C $(BUILDDIR)/texinfo info + @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo." + +gettext: + $(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale + @echo + @echo "Build finished. The message catalogs are in $(BUILDDIR)/locale." + +changes: + $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes + @echo + @echo "The overview file is in $(BUILDDIR)/changes." + +linkcheck: + $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck + @echo + @echo "Link check complete; look for any errors in the above output " \ + "or in $(BUILDDIR)/linkcheck/output.txt." + +doctest: + $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest + @echo "Testing of doctests in the sources finished, look at the " \ + "results in $(BUILDDIR)/doctest/output.txt." diff --git a/docs/api/leap.config.rst b/docs/api/leap.config.rst new file mode 100644 index 00000000..c1462817 --- /dev/null +++ b/docs/api/leap.config.rst @@ -0,0 +1,27 @@ +config Package +============== + +:mod:`leapsettings` Module +-------------------------- + +.. automodule:: leap.config.leapsettings + :members: + :undoc-members: + :show-inheritance: + +:mod:`provider_spec` Module +--------------------------- + +.. automodule:: leap.config.provider_spec + :members: + :undoc-members: + :show-inheritance: + +:mod:`providerconfig` Module +---------------------------- + +.. automodule:: leap.config.providerconfig + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/leap.crypto.rst b/docs/api/leap.crypto.rst new file mode 100644 index 00000000..6db77e86 --- /dev/null +++ b/docs/api/leap.crypto.rst @@ -0,0 +1,34 @@ +crypto Package +============== + +:mod:`constants` Module +----------------------- + +.. automodule:: leap.crypto.constants + :members: + :undoc-members: + :show-inheritance: + +:mod:`srpauth` Module +--------------------- + +.. automodule:: leap.crypto.srpauth + :members: + :undoc-members: + :show-inheritance: + +:mod:`srpregister` Module +------------------------- + +.. automodule:: leap.crypto.srpregister + :members: + :undoc-members: + :show-inheritance: + +Subpackages +----------- + +.. toctree:: + + leap.crypto.tests + diff --git a/docs/api/leap.crypto.tests.rst b/docs/api/leap.crypto.tests.rst new file mode 100644 index 00000000..f9e32580 --- /dev/null +++ b/docs/api/leap.crypto.tests.rst @@ -0,0 +1,27 @@ +tests Package +============= + +:mod:`tests` Package +-------------------- + +.. automodule:: leap.crypto.tests + :members: + :undoc-members: + :show-inheritance: + +:mod:`fake_provider` Module +--------------------------- + +.. automodule:: leap.crypto.tests.fake_provider + :members: + :undoc-members: + :show-inheritance: + +:mod:`test_srpregister` Module +------------------------------ + +.. automodule:: leap.crypto.tests.test_srpregister + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/leap.gui.rst b/docs/api/leap.gui.rst new file mode 100644 index 00000000..1559e079 --- /dev/null +++ b/docs/api/leap.gui.rst @@ -0,0 +1,59 @@ +gui Package +=========== + +:mod:`locale_rc` Module +----------------------- + +.. automodule:: leap.gui.locale_rc + :members: + :undoc-members: + :show-inheritance: + +:mod:`mainwindow` Module +------------------------ + +.. automodule:: leap.gui.mainwindow + :members: + :undoc-members: + :show-inheritance: + +:mod:`mainwindow_rc` Module +--------------------------- + +.. automodule:: leap.gui.mainwindow_rc + :members: + :undoc-members: + :show-inheritance: + +:mod:`ui_mainwindow` Module +--------------------------- + +.. automodule:: leap.gui.ui_mainwindow + :members: + :undoc-members: + :show-inheritance: + +:mod:`ui_wizard` Module +----------------------- + +.. automodule:: leap.gui.ui_wizard + :members: + :undoc-members: + :show-inheritance: + +:mod:`wizard` Module +-------------------- + +.. automodule:: leap.gui.wizard + :members: + :undoc-members: + :show-inheritance: + +:mod:`wizardpage` Module +------------------------ + +.. automodule:: leap.gui.wizardpage + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/leap.platform_init.rst b/docs/api/leap.platform_init.rst new file mode 100644 index 00000000..a638df35 --- /dev/null +++ b/docs/api/leap.platform_init.rst @@ -0,0 +1,27 @@ +platform_init Package +===================== + +:mod:`platform_init` Package +---------------------------- + +.. automodule:: leap.platform_init + :members: + :undoc-members: + :show-inheritance: + +:mod:`initializers` Module +-------------------------- + +.. automodule:: leap.platform_init.initializers + :members: + :undoc-members: + :show-inheritance: + +:mod:`locks` Module +------------------- + +.. automodule:: leap.platform_init.locks + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/leap.rst b/docs/api/leap.rst new file mode 100644 index 00000000..0f03c9e4 --- /dev/null +++ b/docs/api/leap.rst @@ -0,0 +1,24 @@ +leap Package +============ + +:mod:`leap` Package +------------------- + +.. automodule:: leap + :members: + :undoc-members: + :show-inheritance: + + +Subpackages +----------- + +.. toctree:: + + leap.config + leap.crypto + leap.gui + leap.platform_init + leap.services + leap.util + diff --git a/docs/api/leap.services.eip.rst b/docs/api/leap.services.eip.rst new file mode 100644 index 00000000..0cf489cf --- /dev/null +++ b/docs/api/leap.services.eip.rst @@ -0,0 +1,59 @@ +eip Package +=========== + +:mod:`eipbootstrapper` Module +----------------------------- + +.. automodule:: leap.services.eip.eipbootstrapper + :members: + :undoc-members: + :show-inheritance: + +:mod:`eipconfig` Module +----------------------- + +.. automodule:: leap.services.eip.eipconfig + :members: + :undoc-members: + :show-inheritance: + +:mod:`eipspec` Module +--------------------- + +.. automodule:: leap.services.eip.eipspec + :members: + :undoc-members: + :show-inheritance: + +:mod:`providerbootstrapper` Module +---------------------------------- + +.. automodule:: leap.services.eip.providerbootstrapper + :members: + :undoc-members: + :show-inheritance: + +:mod:`udstelnet` Module +----------------------- + +.. automodule:: leap.services.eip.udstelnet + :members: + :undoc-members: + :show-inheritance: + +:mod:`vpn` Module +----------------- + +.. automodule:: leap.services.eip.vpn + :members: + :undoc-members: + :show-inheritance: + +:mod:`vpnlaunchers` Module +-------------------------- + +.. automodule:: leap.services.eip.vpnlaunchers + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/leap.services.rst b/docs/api/leap.services.rst new file mode 100644 index 00000000..1a35ab5b --- /dev/null +++ b/docs/api/leap.services.rst @@ -0,0 +1,10 @@ +services Package +================ + +Subpackages +----------- + +.. toctree:: + + leap.services.eip + diff --git a/docs/api/leap.util.rst b/docs/api/leap.util.rst new file mode 100644 index 00000000..85eb79da --- /dev/null +++ b/docs/api/leap.util.rst @@ -0,0 +1,43 @@ +util Package +============ + +:mod:`util` Package +------------------- + +.. automodule:: leap.util + :members: + :undoc-members: + :show-inheritance: + +:mod:`checkerthread` Module +--------------------------- + +.. automodule:: leap.util.checkerthread + :members: + :undoc-members: + :show-inheritance: + +:mod:`leap_argparse` Module +--------------------------- + +.. automodule:: leap.util.leap_argparse + :members: + :undoc-members: + :show-inheritance: + +:mod:`privilege_policies` Module +-------------------------------- + +.. automodule:: leap.util.privilege_policies + :members: + :undoc-members: + :show-inheritance: + +:mod:`request_helpers` Module +----------------------------- + +.. automodule:: leap.util.request_helpers + :members: + :undoc-members: + :show-inheritance: + diff --git a/docs/api/modules.rst b/docs/api/modules.rst new file mode 100644 index 00000000..d49776ae --- /dev/null +++ b/docs/api/modules.rst @@ -0,0 +1,7 @@ +leap +==== + +.. toctree:: + :maxdepth: 4 + + leap diff --git a/docs/checklist_for_leap_client_release.wiki b/docs/checklist_for_leap_client_release.wiki new file mode 100644 index 00000000..5abced80 --- /dev/null +++ b/docs/checklist_for_leap_client_release.wiki @@ -0,0 +1,45 @@ += LEAP CLient Release Checklist (*) = + + * [ ] validate rc + * [ ] all rc-critical closed! + * [ ] all bbots green + * [ ] uploaded translations: make translations + * [ ] re-generate pyqt resources + + * [ ] update docs + * [ ] CREDITS + * [ ] relnotes.txt + * [ ] docs/known_issues.rst + * [ ] NEWS.rst: Add release name and date to top-most item in NEWS. + + * [ ] change docs/quickstart.rst to point to just the current + leap-client-X.Y.Z.deb binaries and .tar.gz source code files + * [ ] on release/vX.Y.Z branch: git pull + * [ ] git tag X.Y.Z + * [ ] build locally to make sure the release is reporting itself as the + intended version (FIXME!) + * [ ] make sure buildbot is green + * [ ] make sure other people aren't committing at that moment + * [ ] FUTURE: push tag along with some other documentation-only patch (typically to + relnotes.txt) to trigger buildslaves + * [ ] git push --tags official; git push official + * [ ] that will build tarballs + * [ ] make sure buildbot is green (in a parallel universe, he) + * [ ] download tarballs, sign with "gpg -ba -u deadbeef TAR", upload *.asc + * [ ] symlink the release tarball on leap.se downloads page: + /var/www/source/leap-client/releases/ CHANGEME XXX + + * [ ] update news pages. release notes. + * [ ] send out relnotes.txt to internal list. + * [ ] wait ...? + + * [ ] PYPI UPLOAD: with "python ./setup.py sdist upload register" + + * [ ] make an "announcement of new release" on leap.se + * [ ] close the Milestone on the chili Roadmap + * [ ] send out relnotes.txt to: + * [ ] mailing lists... + +notes +----- +(*) this checklist kindly borrowed from tahoe-lafs documentation =) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 00000000..4a90d7d5 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,242 @@ +# -*- coding: utf-8 -*- +# +# LEAP documentation build configuration file, created by +# sphinx-quickstart on Sun Jul 22 18:32:05 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'index' + +# General information about the project. +project = u'LEAP' +copyright = u'2012, The LEAP Encryption Access Project' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '0.2.1-dev1' +# The full version, including alpha/beta/rc tags. +release = '0.2.1' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +language = "en_US" + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# "<project> v<release> documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +html_logo = "../data/images/leap-color-small.png" + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +html_favicon = "../data/images/favicon.ico" + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a <link> tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'LEAPdoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [ + ('index', 'LEAP.tex', u'LEAP Documentation', + u'The Leap Project', 'manual'), +] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('index', 'leap', u'LEAP Documentation', + [u'The Leap Project'], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('index', 'LEAP', u'LEAP Documentation', + u'The Leap Project', 'LEAP', 'One line description of project.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/config/files.rst b/docs/config/files.rst new file mode 100644 index 00000000..0f4abead --- /dev/null +++ b/docs/config/files.rst @@ -0,0 +1,16 @@ +.. _files: + +Configuration Files +=================== + +This document covers the different configuration files used by the LEAP Client. + +leap.conf +--------- + +TBD + +eip.json +-------- + +TBD diff --git a/docs/dev/authors.rst b/docs/dev/authors.rst new file mode 100644 index 00000000..db32bd94 --- /dev/null +++ b/docs/dev/authors.rst @@ -0,0 +1,8 @@ +.. _authors: + +Authors +======= + +We are many. +We are legion. + diff --git a/docs/dev/environment.rst b/docs/dev/environment.rst new file mode 100644 index 00000000..010ccc83 --- /dev/null +++ b/docs/dev/environment.rst @@ -0,0 +1,126 @@ +.. _environment: + +Setting up a development environment +==================================== + +This document covers how to get an enviroment ready to contribute code to the LEAP Client. + +Cloning the repo +---------------- +.. note:: + Stable releases are in *master* branch. + Development code lives in *develop* branch. + +:: + + git clone git://leap.se/leap_client + git checkout develop + +Base Dependencies +------------------ +Leap client depends on these libraries: + +* `python 2.6 or 2.7` +* `qt4` libraries (see also :ref:`Troubleshooting PySide install <pysidevirtualenv>` about how to install inside your virtualenv) +* `openssl` +* `openvpn <http://openvpn.net/index.php/open-source/345-openvpn-project.html>`_ + +Debian +^^^^^^ +In debian-based systems:: + + $ apt-get install openvpn python-pyside python-openssl + +To install the software from sources:: + + $ apt-get install python-pip python-dev + +.. _virtualenv: + +Working with virtualenv +----------------------- + +Intro +^^^^^^^^^^^^^^^^^^^ + +*Virtualenv* is the *Virtual Python Environment builder*. + +It is a tool to create isolated Python environments. + +The basic problem being addressed is one of dependencies and versions, and indirectly permissions. Imagine you have an application that needs version 1 of LibFoo, but another application requires version 2. How can you use both these applications? If you install everything into /usr/lib/python2.7/site-packages (or whatever your platform's standard location is), it's easy to end up in a situation where you unintentionally upgrade an application that shouldn't be upgraded. + +Read more about it in the `project documentation page <http://pypi.python.org/pypi/virtualenv/>`_. + +.. note:: + this section could be completed with useful options that can be passed to the virtualenv command (e.g., to make portable paths, site-packages, ...). We also should document how to use virtualenvwrapper. + + + +Create and activate your dev environment +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +:: + + $ virtualenv </path/to/new/environment> + $ source </path/to/new/environment>/bin/activate + +.. _pysidevirtualenv: + +Avoid compiling PySide inside a virtualenv +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you attempt to install PySide inside a virtualenv as part of the rest of the dependencies using pip, basically it will take ages to compile. + +As a workaround, you can run the following script after creating your virtualenv. It will symlink to your global PySide installation (*this is the recommended way if you are running a debian-based system*):: + + $ pkg/postmkvenv.sh + +A second option if that does not work for you would be to install PySide globally and pass the ``--site-packages`` option when you are creating your virtualenv:: + + $ apt-get install python-pyside + $ virtualenv --site-packages . + +After that, you must export ``LEAP_VENV_SKIP_PYSIDE`` to skip the isntallation:: + + $ export LEAP_VENV_SKIP_PYSIDE=1 + +And now you are ready to proceed with the next section. + +.. _pydepinstall: + +Install python dependencies +^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +You can install python dependencies with ``pip``. If you do it inside your working environment, they will be installed avoiding the need for administrative permissions:: + + $ pip install -r pkg/requirements.pip + + +.. _copyscriptfiles: + +Copy script files +----------------- + +The openvpn invocation expects some files to be in place. If you have not installed `leap-client` from a debian package, you must copy these files manually by now:: + + $ sudo mkdir -p /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap + +.. _policykit: + +Running openvpn without root privileges +--------------------------------------- + +In linux, we are using ``policykit`` to be able to run openvpn without root privileges, and a policy file is needed to be installed for that to be possible. +The setup script tries to install the policy file when installing the client system-wide, so if you have installed the client in your global site-packages at least once it should have copied this file for you. + +If you *only* are running the client from inside a virtualenv, you will need to copy this file by hand:: + + $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + + +Missing Authentication agent +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +If you are running a desktop other than gnome or unity, you might get an error saying that you are not running the authentication agent. You can launch it like this:: + + /usr/lib/policykit-1-gnome/polkit-gnome-authentication-agent-1 & diff --git a/docs/dev/internals.rst b/docs/dev/internals.rst new file mode 100644 index 00000000..8bb19211 --- /dev/null +++ b/docs/dev/internals.rst @@ -0,0 +1,12 @@ +.. _internals: + +Internals +========= + +This section covers briefly the internal organization of the LEAP Client source tree. + +.. note:: + + very unfinished. + +`TBD` diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst new file mode 100644 index 00000000..1a9af0be --- /dev/null +++ b/docs/dev/internationalization.rst @@ -0,0 +1,117 @@ +.. _i18n: + +Internationalization +==================== + +This part of the documentation covers the localization and translation of LEAP Client. +Because we want to *bring fire to the people*, in as many countries and languages as possible. + +Translating the LEAP Client PyQt Application +-------------------------------------------- + +.. raw:: html + + <div><a target="_blank" style="text-decoration:none; color:black; font-size:66%" href="https://www.transifex.com/projects/p/leap-client/resource/leap-client/" title="See more information on Transifex.com">Top translations: leap-client » leap-client</a><br/><img border="0" src="https://www.transifex.com/projects/p/leap-client/resource/leap-client/chart/image_png"/><br/><a target="_blank" href="https://www.transifex.com/"><img border="0" src="https://ds0k0en9abmn1.cloudfront.net/static/charts/images/tx-logo-micro.646b0065fce6.png"/></a></div> + + +For translators +^^^^^^^^^^^^^^^ +.. note:: + We should probably move the translators info to a top level section of the docs, and leave this + as internal notes. + + +We are using `transifex <http://transifex.com/projects/p/leap-client>`_ to coordinate translation efforts. If you want to contribute, just sign up there and ... + +.. note:: + ... and what?? + +For devs: i18n conventions +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. note:: + should say something about our special cases (provider labels and exceptions) when we get decision about it. + +Refer to `pyqt documentation <http://www.riverbankcomputing.co.uk/static/Docs/PyQt4/html/i18n.html>`_. + +tl;dr;:: + + self.tr('your string') + +for any string that you want to be translated, as long as the instance derives from ``QObject``. + +If you have to translate something that it is not a ``QObject``, use the magic leap ``translate`` method: + + +.. code-block:: python + + from leap.util.translations import translate + + class Foo(object): + bar = translate(<Context>, <string>, <comment>) + + +.. Note about this: there seems to be some problems with the .tr method + so the translate method could actually be the preferred thing in all the cases. + Still missing what to do for language labels (json-based). + --kali + +For i18n maintainers +^^^^^^^^^^^^^^^^^^^^ + +You need ``pylupdate4`` and ``lrelease`` for these steps. To get it, in debian:: + + $ apt-get install pyqt4-dev-tools qt4-linguist-tools + +If you do not already have it, install the ``transifex-client`` from the cheese shop:: + + pip install transifex-client + +You can learn more about the transifex-client `here <http://help.transifex.com/features/client/index.html>`_. + +**1.** Add any new source files to the project file, ``data/leap_client.pro``. *We should automate this with some templating, it's tedious.* + +**2.** Update the source .ts file ``data/ts/en_US.ts``.:: + + $ make translations + +**3.** Push source .ts file to transifex:: + + $ tx push -s + +**4.** Let the translation fairies do their work... + +**5.** *Et voila!* Get updated .ts files for each language from ``Transifex``. For instance, to pull updated spanish translations:: + + $ tx pull -l es + Pulling new translations for resource leap-client.leap-client (source: data/ts/en_US.ts) + -> es: data/translations/es.ts + Done. + + +Note that there is a configuration option in ``.tx/config`` for setting the minimum completion percentage needed to be able to actually pull a resource. + +**6.** Generate .qm files from the updated .ts files:: + + $ make translations + +and yes, it's the same command than in step 2. One less thing to remember :) + +**7.** Check that the .qm for the language you're working with is listed in ``data/resources/locale.qrc`` file. That should take the translated files from ``data/translations`` + +**8.** Re-generate ``src/leap/gui/locale_qrc``. This is the embedded resource file that we load in the main app entry point; and from where we load the data for the qt translator object:: + + $ make resources + +If you want to try it, just set your LANG environment variable:: + + $ LANG=es_ES leap-client + + +Translating the Documentation +------------------------------ + +.. note:: + ...unfinished + +`translating sphinx docs <http://sphinx-doc.org/intl.html>`_ diff --git a/docs/dev/resources.rst b/docs/dev/resources.rst new file mode 100644 index 00000000..7cfa2b70 --- /dev/null +++ b/docs/dev/resources.rst @@ -0,0 +1,14 @@ +.. _resources: + +PyQt Resource files +=================== + +Compiling resource/ui files +--------------------------- + +You should refresh resource/ui files every time you change an image or a resource/ui (.ui / .qc). From the root folder:: + + % make ui + % make resources + +As there are some tests to guard against unwanted resource updates, you will have to update the resource hash in those failing tests. diff --git a/docs/dev/tests.rst b/docs/dev/tests.rst new file mode 100644 index 00000000..7f5fbaaf --- /dev/null +++ b/docs/dev/tests.rst @@ -0,0 +1,62 @@ +.. _tests: + +Running and writing tests +========================= + +.. note:: + should include seeAlso to virtualenv + +This section covers the documentation about the tests for the LEAP Client code. +All patches should have tests for them ... + + +Testing dependencies +-------------------- + +have a look at ``pkg/test-requirements.pip`` +The ``./run_tests.sh`` command should install all of them in your virtualenv for you. + +If you prefer to install them system wide, this should do in a debian system:: + + $ apt-get install python-nose python-mock python-coverage + + +Running tests +------------- + +There is a convenience script at ``./run_tests.sh`` + +If you want to run specific tests, pass the (sub)module to nose:: + + $ nosetests leap.util + +or:: + + $ nosetests leap.util.tests.test_leap_argparse + +Hint: colorized output +^^^^^^^^^^^^^^^^^^^^^^ + +Install ``rednose`` locally, export the ``NOSE_REDNOSE`` variable, and give your eyes a rest :):: + + (leap_client)% pip install rednose + (leap_client)% export NOSE_REDNOSE=1 + +Testing all the supported python versions +----------------------------------------- + +For running testsuite against all the supported python versions (currently 2.6 and 2.7), run:: + + % tox -v + +Coverage reports +---------------- + +Pass the ``-c`` flat to the ``run_tests.sh`` script:: + + $ run_tests.sh -c + +Using ``coverage`` it will generate beautiful html reports that you can access pointing your browser to ``docs/covhtml/index.html`` + +.. note:: + The coverage reports will not be generated if all tests are not passing. diff --git a/docs/dev/todo.rst b/docs/dev/todo.rst new file mode 100644 index 00000000..c50eac09 --- /dev/null +++ b/docs/dev/todo.rst @@ -0,0 +1,6 @@ +.. _todo: + +To-Do +===== + +alot diff --git a/docs/dev/workflow.rst b/docs/dev/workflow.rst new file mode 100644 index 00000000..e36431ff --- /dev/null +++ b/docs/dev/workflow.rst @@ -0,0 +1,43 @@ +.. _workflow: + +Development Workflow +==================== + +This section documents the workflow that the LEAP project team follows and expects for the code contributions. + +Code formatting +--------------- +In one word: `PEP8`_. + +`autopep8` might be your friend. or eat your code. + +.. _`PEP8`: http://www.python.org/dev/peps/pep-0008/ +.. _`autopep8`: http://pypi.python.org/pypi/autopep8 + +Dependencies +------------ +If you introduce a new dependency, please add it under ``pkg/requirements`` or ``pkg/test-requirements`` as appropiate, under the proper module section. + +Git flow +-------- +We are basing our workflow on what is described in `A successful git branching model <http://nvie.com/posts/a-successful-git-branching-model/>`_. + +.. image:: https://leap.se/code/attachments/13/git-branching-model.png + +The author of the aforementioned post has also a handy pdf version of it: `branching_model.pdf`_ + +However, we use a setup in which each developer maintains her own feature branch in her private repo. After a code review, this feature branch is rebased onto the authoritative integration branch. Thus, the leapcode repo in leap.se (mirrored in github) only maintains the master and develop branches. + +A couple of tools that help to follow this process are `git-flow`_ and `git-sweep`_. + +.. _`branching_model.pdf`: https://leap.se/code/attachments/14/Git-branching-model.pdf +.. _`git-flow`: https://github.com/nvie/gitflow +.. _`git-sweep`: http://pypi.python.org/pypi/git-sweep + +Code review and merges into integration branch +----------------------------------------------- +All code ready to be merged into the integration branch is expected to: + +* Have tests +* Be documented +* Pass existing tests: do **run_tests.sh** and **tox -v**. All feature branches are automagically built by our `buildbot farm <http://lemur.leap.se:8010/grid>`_. So please check your branch is green before merging it it to `develop`. Rebasing against the current tip of the integration when possible is preferred in order to keep a clean history. diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 00000000..e3078929 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,89 @@ +.. LEAP documentation master file, created by + sphinx-quickstart on Sun Jul 22 18:32:05 2012. + You can adapt this file completely to your liking, but it should at least + contain the root `toctree` directive. + +LEAP Client +===================================== + +Release v\ |version|. (`Impatient? jump to the` :ref:`Installation <install>` `section!`) + +.. if you change this paragraph, change it in user/intro too +The **LEAP Encryption Access Project Client** is a :ref:`GPL3 Licensed <gpl3>` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform <leapplatform>`. Currently is being tested on Linux, support for OSX and Windows will come soon. + +User Guide +---------- + +.. toctree:: + :maxdepth: 2 + + user/intro + user/install + user/running + +Tester Guide +------------ + +This part of the documentation details how to fetch the last development version and how to report bugs. + +.. toctree:: + :maxdepth: 1 + + testers/howto + +Hackers Guide +--------------- + +If you want to contribute to the project, we wrote this for you. + +.. toctree:: + :maxdepth: 1 + + dev/environment + dev/tests + dev/workflow + dev/resources + dev/internationalization + +.. dev/internals + dev/authors + dev/todo + dev/workflow + +Packager Guide +--------------- + +Docs related to the process of building and releasing a version of the client. + +.. toctree:: + :maxdepth: 1 + + pkg/debian + pkg/osx + pkg/win + + +Directories and Files +--------------------- + +Different directories and files used for the configuration of the client. + +.. toctree:: + :maxdepth: 1 + + config/files + + +API Documentation +----------------- + +If you are looking for a reference to specific classes or functions, you are likely to find it here. + +.. I should investigate a bit more how to skip some things, and how to give nice format + to the docstrings. + Maybe we should not have sphinx-apidocs building everything, but a minimal index of our own. + +.. toctree:: + :maxdepth: 2 + + api/leap diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 00000000..b241ea34 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,190 @@ +@ECHO OFF + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set BUILDDIR=_build +set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . +set I18NSPHINXOPTS=%SPHINXOPTS% . +if NOT "%PAPER%" == "" ( + set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% + set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% +) + +if "%1" == "" goto help + +if "%1" == "help" ( + :help + echo.Please use `make ^<target^>` where ^<target^> is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* + goto end +) + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\LEAP.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\LEAP.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +:end diff --git a/docs/man/leap-client.1.rst b/docs/man/leap-client.1.rst new file mode 100644 index 00000000..1ef5b3cc --- /dev/null +++ b/docs/man/leap-client.1.rst @@ -0,0 +1,86 @@ +=========== +leap-client +=========== + +------------------------------------------------------------------------ +graphical client to control LEAP, the encrypted internet access toolkit. +------------------------------------------------------------------------ + +:Author: LEAP Encryption Access Project https://leap.se +:Date: 2013-01-30 +:Copyright: GPLv3+ +:Version: 0.2 +:Manual section: 1 +:Manual group: General Commands Manual + +SYNOPSIS +======== + +leap-client [-h] [-d] [-l [LOG FILE]] [--openvpn-verbosity [OPENVPN_VERB]] + +DESCRIPTION +=========== + +*leap-client* is a graphical client to control LEAP, the encrypted internet access toolkit. + +When launched, it places an icon in the system tray from where the LEAP services can be controlled. + + +OPTIONS +======= + +general options +--------------- + +**-h, --help** Print a help message and exit. + +**-d, --debug** Launches client in debug mode, writing debug info to stdout. + +**---logfile=<file>** Writes log to file. + +openvpn options +--------------- + +**--openvpn-verbosity** [0-5] Verbosity level for openvpn logs. + + +WARNING +======= + +This software is still in early alfa testing. So don't trust your life to it! + +At the current time, the LEAP Client is not compatible with ``openresolv``, but it works with ``resolvconf``. + +FILES +===== + +/etc/leap/resolv-update +----------------------- +Post up/down script passed to openvpn. It writes /etc/resolv.conf to avoid dns leaks, and restores the original resolv.conf on exit. + +/etc/leap/resolv-head +--------------------- +/etc/leap/resolv-tail +--------------------- + +Custom entries that will appear in the written resolv.conf + +/usr/share/polkit-1/actions/net.openvpn.gui.leap.policy +------------------------------------------------------- + +PolicyKit policy file, used for granting access to openvpn without the need of entering a password each time. + +~/.config/leap/ +--------------- + +Main config folder + +~/.config/leap/leap.conf +------------------------ + +GUI options + +BUGS +==== + +Please report any bugs to https://leap.se/code diff --git a/docs/pkg/debian.rst b/docs/pkg/debian.rst new file mode 100644 index 00000000..e98032a5 --- /dev/null +++ b/docs/pkg/debian.rst @@ -0,0 +1,28 @@ +.. _debian: + +Debian +====== + +This section documents all related to the debian package. + + +Dependencies +------------ + +* ``openvpn`` +* ``python-qt4`` +* ``python-crypto`` +* ``python setuptools`` +* ``python-requests`` +* ``python-openssl`` + +.. note:: + these need a version that is not found in the current debian stable or in ubuntu 12.04. + They will be packaged... soon. + +* ``python-keyring`` + +For tests +^^^^^^^^^ +* ``python-nose``, ``python-mock``, ``python-coverage`` + diff --git a/docs/pkg/osx.rst b/docs/pkg/osx.rst new file mode 100644 index 00000000..dca018b6 --- /dev/null +++ b/docs/pkg/osx.rst @@ -0,0 +1,7 @@ +.. _osx: + +OS X +===== + +Nothing here +move on diff --git a/docs/pkg/win.rst b/docs/pkg/win.rst new file mode 100644 index 00000000..ef2cec5f --- /dev/null +++ b/docs/pkg/win.rst @@ -0,0 +1,7 @@ +.. _win: + +Windows +======= + +Nothing here +move on diff --git a/docs/testers/howto.rst b/docs/testers/howto.rst new file mode 100644 index 00000000..a3f8da09 --- /dev/null +++ b/docs/testers/howto.rst @@ -0,0 +1,115 @@ +.. _testhowto: + +Howto for Testers +================= + +This document covers a how-to guide to: + +#. Quickly fetching latest development code, and +#. Reporting bugs. + +Let's go! + +.. _fetchinglatest: + +Fetching latest development code +--------------------------------- + +To allow rapid testing in different platforms, we have put together a quick script that is able to fetch latest development code. It more or less does all the steps covered in the :ref:`Setting up a Work Enviroment <environment>` section, only that in a more compact way suitable (ahem) also for non developers. + +.. note:: + + In the near future, we will be using ``standalone bundles`` with the ability to self-update. + +Install dependencies +^^^^^^^^^^^^^^^^^^^^ +First, install all the base dependencies plus git, virtualenv and development files needed to compile several extensions:: + + apt-get install openvpn git-core python-dev python-qt4 python-setuptools python-virtualenv + + +Bootstrap script +^^^^^^^^^^^^^^^^ +.. note:: + This will fetch the *develop* branch. If you want to test another branch, just change it in the line starting with *pip install...*. Alternatively, bug kali so she add an option branch to a decent script. + +.. note:: + This script could make use of the after_install hook. Read http://pypi.python.org/pypi/virtualenv/ + +Download and source the following script in the parent folder where you want your testing build to be downloaded. For instance, to `/tmp/`: + +.. code-block:: bash + + cd /tmp + wget https://raw.github.com/leapcode/leap_client/develop/pkg/scripts/leap_client_bootstrap.sh + source leap_client_bootstrap.sh + +Tada! If everything went well, you should be able to run the client by typing:: + + bin/leap-client + +Noticed that your prompt changed? That was *virtualenv*. Keep reading... + +Activating the virtualenv +^^^^^^^^^^^^^^^^^^^^^^^^^ +The above bootstrap script has fetched latest code inside a virtualenv, which is an isolated, *virtual* python local environment that avoids messing with your global paths. You will notice you are *inside* a virtualenv because you will see a modified prompt reminding it to you (*leap-client-testbuild* in this case). + +Thus, if you forget to *activate your virtualenv*, the client will not run from the local path, and it will be looking for something else in your global path. So, **you have to remember to activate your virtualenv** each time that you open a new shell and want to execute the code you are testing. You can do this by typing:: + + $ source bin/activate + +from the directory where you *sourced* the bootstrap script. + +Refer to :ref:`Working with virtualenv <virtualenv>` to learn more about virtualenv. + +Copying config files +^^^^^^^^^^^^^^^^^^^^ + +If you have never installed the ``leap-client`` globally, **you need to copy some files to its proper path before running it for the first time** (you only need to do this once). This, unless the virtualenv-based operations, will need root permissions. See :ref:`copy script files <copyscriptfiles>` and :ref:`running openvpn without root privileges <policykit>` sections for more info on this. In short:: + + $ sudo cp pkg/linux/polkit/net.openvpn.gui.leap.policy /usr/share/polkit-1/actions/ + $ sudo mkdir -p /etc/leap + $ sudo cp pkg/linux/resolv-update /etc/leap + +Local config files +^^^^^^^^^^^^^^^^^^^ + +If you want to start fresh without config files, just move them. In linux:: + + mv ~/.config/leap ~/.config/leap.old + +Pulling latest changes +^^^^^^^^^^^^^^^^^^^^^^ + +You should be able to cd into the downloaded repo and pull latest changes:: + + (leap-client-testbuild)$ cd src/leap-client + (leap-client-testbuild)$ git pull origin develop + +However, as a tester you are encouraged to run the whole bootstrap process from time to time to help us catching install and versioniing bugs too. + +Testing the packages +^^^^^^^^^^^^^^^^^^^^ +When we have a release candidate for the supported platforms (Debian stable, Ubuntu 12.04 by now), we will announce also the URI where you can download the rc for testing in your system. Stay tuned! + +Testing the status of translations +---------------------------------- + +We need translators! You can go to `transifex <https://www.transifex.com/projects/p/leap-client/>`_, get an account and start contributing. + +If you want to check the current status of the client localization in a language other than the one set in your machine, you can do it with a simple trick (under linux). For instance, do:: + + $ lang=es_ES leap-client + +for running LEAP Client with the spanish locales. + +Reporting bugs +-------------- + +.. admonition:: Reporting better bugs + + There is a great text on the art of bug reporting, that can be found `online <http://www.chiark.greenend.org.uk/~sgtatham/bugs.html>`_. + +.. TODO add a line with ref. to running the client in debug mode... + +We use the `LEAP Client Bug Tracker <https://leap.se/code/projects/eip-client>`_, although you can also use `Github issues <https://github.com/leapcode/leap_client/issues>`_. diff --git a/docs/user/install.rst b/docs/user/install.rst new file mode 100644 index 00000000..0467ba8b --- /dev/null +++ b/docs/user/install.rst @@ -0,0 +1,61 @@ +.. _install: + +Installation +============ + +This part of the documentation covers the installation of the LEAP Client. +We assume that you want to get it properly installed before being able to use it. + +.. note:: + + The recommended way of installing in the near future will be the standalone bundles, but those are not quite ready yet. Methods described in this page assume you are familiar with python code, and you can find your way through the process of dependencies install. You can refer to the sections :ref:`setting up a working environment <environment>` or :ref:`fetching latest code for testing <fetchinglatest>`. + + +Distribute & Pip +---------------- + +.. warning:: The package in the cheese shop is from the stable, `0.2.0` release, which is now outdated. You are encouraged to install the development version instead. + +Installing LEAP Client is as simple as using `pip <http://www.pip-installer.org/>`_ for the already released versions :: + + $ pip install leap-client + +Debian package +-------------- + +.. warning:: + + The debian package in the leap repositories is from the stable, `0.2.0` release, which is now outdated. You are encouraged to install the development version instead, + +First, you need to bootstrap your apt-key:: + + # gpg --recv-key 0x1E34A1828E207901 0x485B12FA218E81EB + # gpg --list-sigs 0x1E34A1828E207901 + # gpg --list-sigs 0x485B12FA218E81EB + # gpg -a --export 0x1E34A1828E207901 | sudo apt-key add - + +Add the archive to your sources.list:: + + # echo "deb http://deb.leap.se/debian unstable main" >> /etc/apt/sources.list + # apt-get update + # apt-get install leap-keyring + +And then you can happily install leap-client:: + + apt-get install leap-client + +Show me the code! +----------------- + +You can get the code from LEAP public git repository :: + + $ git clone git://leap.se/leap_client + +Or from the github mirror :: + + $ git clone git://github.com/leapcode/leap_client.git + +Once you have grabbed a copy of the sources, you can install it into your site-packages easily :: + + $ pyton setup.py install + diff --git a/docs/user/intro.rst b/docs/user/intro.rst new file mode 100644 index 00000000..9461d5f2 --- /dev/null +++ b/docs/user/intro.rst @@ -0,0 +1,101 @@ +.. _introduction: + +Introduction +============ + +The LEAP Client +--------------- +.. if yoy change this, change it also in the index.rst +The **LEAP Client** is a :ref:`GPL3 Licensed <gpl3>` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform <leapplatform>`. Currently is being tested on Linux, support for OSX and Windows will come soon. + +Features +^^^^^^^^ + +The LEAP Client allows to easily secure communications. + +- Provider selection +- User registration +- Encrypted Internet Proxy support (autoconfigured service using openvpn). + +Coming soon +^^^^^^^^^^^^ + +- Encrypted email + +.. _leapplatform: + +The LEAP Platform +^^^^^^^^^^^^^^^^^ +The LEAP Provider Platform is the server-side part of LEAP that is run by service providers. It consists of a set of complementary packages and recipes to automate the maintenance of LEAP services in a hardened GNU/Linux environment. Our goal is to make it painless for service providers and ISPs to deploy a secure communications platform. + +Read `more about the LEAP Platform <https://leap.se/en/technology/platform>`_ or `check out the code <https://github.com/leapcode/leap_platform>`_. + + +.. _philosophy: + +Philosophy +---------- + +The Right to Whisper +^^^^^^^^^^^^^^^^^^^^ +LEAP fights for *the right to whisper*. + +Like free speech, the right to whisper is an necessary precondition for **a free society**. Without it, civil society and political freedom become impossible. As the importance of digital communication for civic participation increases, so does the importance of the ability to digitally whisper. + +Unfortunately, advances in surveillance technology are rapidly eroding the ability to whisper. This is a worldwide problem, not simply an issue for people in repressive contexts. Acceptance of poor security in the West creates a global standard of insecure practice, even among civil society actors who urgently need the ability to communicate safely. + +The stakes could not be higher. Activists are dying because their communication technologies betray their identity, location, and conversations. When activists attempt to secure their communications, they face confusing software, a dearth of secure providers, and a greater risk of being flagged as potential troublemakers. In other words, problems of usability, availability, and adoption. + +Our vision +^^^^^^^^^^ +The LEAP vision is to attack these problems of usability, availability, and adoption head on. + +To address **usability**: + we are creating a complete system where the user-facing client software is + tightly coupled with the cloud-base components of the system. All our software + will be auto-configuring, prevent users from practicing insecure behavior, and + primarily limit the configuration options to those moments when the user is placing i + their trust in another entity. + +To address **availability**: + LEAP will work closely with service providers to adopt our open source, automatedl + platform for running high-availability communication services. By lowering the + barriers of entry to become a reliable provider, we can increase the supply and + decrease the cost of secure communications. + +To address **adoption**: + the LEAP platform layers higher security on top of existing protocols to allow + users a gradual transition path and backward compatibility. Our goal is to create + services that are attractive in terms of features, usability, and price for users in + both democratic and repressive contexts. + +All contributions should have these three points in mind. + +.. _`gpl3`: + +GPLv3 License +-------------- + +.. image:: gpl.* + +The LEAP Client is released under the terms of the `GNU GPL version 3`_ or later. + +:: + + The LEAP Client is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or + (at your option) any later version. + + The LEAP Client is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + + You should have received a copy of the GNU General Public License + along with the LEAP Client. If not, see http://www.gnu.org/licenses/. + +.. _`GNU GPL version 3`: http://www.gnu.org/licenses/gpl.txt + +.. ??? include whole version? + .. include:: ../COPYING diff --git a/docs/user/running.rst b/docs/user/running.rst new file mode 100644 index 00000000..43f3e87c --- /dev/null +++ b/docs/user/running.rst @@ -0,0 +1,44 @@ +.. _running: + +Running +================== + +This document covers how to launch the LEAP Client. + +Launching the client +-------------------- +After a successful installation, there should be a launcher called `leap-client` somewhere in your path:: + + % leap-client + +The first time you launch it, it should launch the first run wizard that will guide you through the setup of the LEAP Services. + +.. note:: + + You will need to enter a valid test provider running the LEAP Platform. You can use the LEAP test service, *https://bitmask.net* + +.. _debugmode: + +Debug mode +---------- +If you are happy having lots of output in your terminal, you will like to know that you can run the client in debug mode:: + + $ leap-client --debug + +If you ask for it, you can also have all that debug info in a beautiful file ready to be attached to your bug reports:: + + $ leap-client --debug --logfile /tmp/leap.log + +.. warning +.. the following is broken since it will clutter your stdout with all the commands sent to the management interface. + See bug #1232 + +.. not working... +.. If you want to increment the level of verbosity passed to openvpn, you can do:: +.. $ leap-client --openvpn-verbosity 4 + +Options +------------ +To see all the available command line options:: + + $ leap-client --help |