From 96eaddedd7f09fcbcc390aedd7078aeecfa4c885 Mon Sep 17 00:00:00 2001 From: kali Date: Fri, 3 May 2013 02:59:22 +0900 Subject: updated documentation * documentation reviewed after rewrite, ready for 0.2.1 * updated docstrings format to fit sphinx autodoc --- changes/feature_update-docs | 2 + docs/Makefile | 153 ++++++++++++++++ docs/api/leap.config.rst | 27 +++ docs/api/leap.crypto.rst | 34 ++++ docs/api/leap.crypto.tests.rst | 27 +++ docs/api/leap.gui.rst | 59 +++++++ docs/api/leap.platform_init.rst | 27 +++ docs/api/leap.rst | 24 +++ docs/api/leap.services.eip.rst | 59 +++++++ docs/api/leap.services.rst | 10 ++ docs/api/leap.util.rst | 43 +++++ docs/api/modules.rst | 7 + docs/checklist_for_leap_client_release.wiki | 45 +++++ docs/conf.py | 242 ++++++++++++++++++++++++++ docs/config/files.rst | 16 ++ docs/dev/authors.rst | 8 + docs/dev/environment.rst | 126 ++++++++++++++ docs/dev/internals.rst | 12 ++ docs/dev/internationalization.rst | 117 +++++++++++++ docs/dev/resources.rst | 14 ++ docs/dev/tests.rst | 62 +++++++ docs/dev/todo.rst | 6 + docs/dev/workflow.rst | 43 +++++ docs/index.rst | 89 ++++++++++ docs/make.bat | 190 ++++++++++++++++++++ docs/man/leap-client.1.rst | 86 +++++++++ docs/pkg/debian.rst | 28 +++ docs/pkg/osx.rst | 7 + docs/pkg/win.rst | 7 + docs/testers/howto.rst | 115 ++++++++++++ docs/user/install.rst | 61 +++++++ docs/user/intro.rst | 101 +++++++++++ docs/user/running.rst | 44 +++++ pkg/requirements-dev.pip | 1 + pkg/scripts/leap_client_bootstrap.sh | 50 ++++++ src/leap/config/leapsettings.py | 69 ++++---- src/leap/config/providerconfig.py | 27 +-- src/leap/crypto/srpauth.py | 68 ++++---- src/leap/crypto/srpregister.py | 22 +-- src/leap/crypto/tests/fake_provider.py | 4 +- src/leap/gui/mainwindow.py | 38 ++-- src/leap/gui/wizard.py | 56 +++--- src/leap/platform_init/locks.py | 18 +- src/leap/services/eip/eipbootstrapper.py | 12 +- src/leap/services/eip/providerbootstrapper.py | 59 +++---- src/leap/services/eip/udstelnet.py | 1 - src/leap/services/eip/vpn.py | 52 +++--- src/leap/services/eip/vpnlaunchers.py | 114 ++++++------ src/leap/util/checkerthread.py | 10 +- src/leap/util/privilege_policies.py | 6 +- src/leap/util/request_helpers.py | 6 +- 51 files changed, 2228 insertions(+), 276 deletions(-) create mode 100644 changes/feature_update-docs create mode 100644 docs/Makefile create mode 100644 docs/api/leap.config.rst create mode 100644 docs/api/leap.crypto.rst create mode 100644 docs/api/leap.crypto.tests.rst create mode 100644 docs/api/leap.gui.rst create mode 100644 docs/api/leap.platform_init.rst create mode 100644 docs/api/leap.rst create mode 100644 docs/api/leap.services.eip.rst create mode 100644 docs/api/leap.services.rst create mode 100644 docs/api/leap.util.rst create mode 100644 docs/api/modules.rst create mode 100644 docs/checklist_for_leap_client_release.wiki create mode 100644 docs/conf.py create mode 100644 docs/config/files.rst create mode 100644 docs/dev/authors.rst create mode 100644 docs/dev/environment.rst create mode 100644 docs/dev/internals.rst create mode 100644 docs/dev/internationalization.rst create mode 100644 docs/dev/resources.rst create mode 100644 docs/dev/tests.rst create mode 100644 docs/dev/todo.rst create mode 100644 docs/dev/workflow.rst create mode 100644 docs/index.rst create mode 100644 docs/make.bat create mode 100644 docs/man/leap-client.1.rst create mode 100644 docs/pkg/debian.rst create mode 100644 docs/pkg/osx.rst create mode 100644 docs/pkg/win.rst create mode 100644 docs/testers/howto.rst create mode 100644 docs/user/install.rst create mode 100644 docs/user/intro.rst create mode 100644 docs/user/running.rst create mode 100644 pkg/scripts/leap_client_bootstrap.sh diff --git a/changes/feature_update-docs b/changes/feature_update-docs new file mode 100644 index 00000000..633b6dcb --- /dev/null +++ b/changes/feature_update-docs @@ -0,0 +1,2 @@ + o Documentation updated for 0.2.1 release + o Docstrings style changed to fit sphinx autodoc format 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 ' where 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 +# " v 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 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 ` about how to install inside your virtualenv) +* `openssl` +* `openvpn `_ + +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 `_. + +.. 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 + $ source /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 + + + + +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 `_ 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 `_. + +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(, , ) + + +.. 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 `_. + +**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 `_ 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 `_. + +.. 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 `_. 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 ` `section!`) + +.. if you change this paragraph, change it in user/intro too +The **LEAP Encryption Access Project Client** is a :ref:`GPL3 Licensed ` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform `. 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 ^` where ^ 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=** 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 ` 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 ` 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 ` and :ref:`running openvpn without root privileges ` 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 `_, 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 `_. + +.. TODO add a line with ref. to running the client in debug mode... + +We use the `LEAP Client Bug Tracker `_, although you can also use `Github 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 ` or :ref:`fetching latest code for testing `. + + +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 `_ 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 ` multiplatform client, written in python using PySide, that supports the features offered by :ref:`the LEAP Platform `. 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 `_ or `check out the code `_. + + +.. _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 diff --git a/pkg/requirements-dev.pip b/pkg/requirements-dev.pip index d00afd06..23d50ceb 100644 --- a/pkg/requirements-dev.pip +++ b/pkg/requirements-dev.pip @@ -12,3 +12,4 @@ # will only install this) -e git+git://github.com/leapcode/leap_pycommon.git@develop#egg=leap.common +sphinx diff --git a/pkg/scripts/leap_client_bootstrap.sh b/pkg/scripts/leap_client_bootstrap.sh new file mode 100644 index 00000000..6c302d3f --- /dev/null +++ b/pkg/scripts/leap_client_bootstrap.sh @@ -0,0 +1,50 @@ +#!/bin/bash + +# Installs requirements, and +# clones the latest leap-client + +# depends on: +# openvpn git-core libgnutls-dev python-dev python-qt4 python-setuptools python-virtualenv + +# Escape code +esc=`echo -en "\033"` + +# Set colors +cc_green="${esc}[0;32m" +cc_yellow="${esc}[0;33m" +cc_blue="${esc}[0;34m" +cc_red="${esc}[0;31m" +cc_normal=`echo -en "${esc}[m\017"` + +echo "${cc_yellow}" +echo "~~~~~~~~~~~~~~~~~~~~~~" +echo "LEAP " +echo "client bootstrapping " +echo "~~~~~~~~~~~~~~~~~~~~~~" +echo "" +echo "${cc_green}Creating virtualenv...${cc_normal}" + +mkdir leap-client-testbuild +virtualenv leap-client-testbuild +source leap-client-testbuild/bin/activate + +echo "${cc_green}Installing leap client...${cc_normal}" + +# Clone latest git (develop branch) +# change "develop" for any other branch you want. + + +pip install -e 'git://leap.se/leap_client@develop#egg=leap-client' + +cd leap-client-testbuild + +# symlink the pyqt libraries to the system libs +./src/leap-client/pkg/postmkvenv.sh + +echo "${cc_green}leap-client installed! =)" +echo "${cc_yellow}" +echo "Launch it with: " +echo "~~~~~~~~~~~~~~~~~~~~~~" +echo "bin/leap-client" +echo "~~~~~~~~~~~~~~~~~~~~~~" +echo "${cc_normal}" diff --git a/src/leap/config/leapsettings.py b/src/leap/config/leapsettings.py index df9c9f11..59a0a16d 100644 --- a/src/leap/config/leapsettings.py +++ b/src/leap/config/leapsettings.py @@ -34,10 +34,10 @@ def to_bool(val): Returns the boolean value corresponding to val. Will return False in case val is not a string or something that behaves like one. - @param val: value to cast - @type val: either bool already or str + :param val: value to cast + :type val: either bool already or str - @rtype: bool + :rtype: bool """ if isinstance(val, bool): return val @@ -70,9 +70,9 @@ class LeapSettings(object): """ Constructor - @param standalone: parameter used to define the location of + :param standalone: parameter used to define the location of the config - @type standalone: bool + :type standalone: bool """ settings_path = os.path.join(get_platform_prefixer() @@ -86,7 +86,7 @@ class LeapSettings(object): """ Returns the saved geometry or None if it wasn't saved - @rtype: bytearray or None + :rtype: bytearray or None """ return self._settings.value(self.GEOMETRY_KEY, None) @@ -94,8 +94,8 @@ class LeapSettings(object): """ Saves the geometry to the settings - @param geometry: bytearray representing the geometry - @type geometry: bytearray + :param geometry: bytearray representing the geometry + :type geometry: bytearray """ leap_assert(geometry, "We need a geometry") self._settings.setValue(self.GEOMETRY_KEY, geometry) @@ -104,7 +104,7 @@ class LeapSettings(object): """ Returns the window state or None if it wasn't saved - @rtype: bytearray or None + :rtype: bytearray or None """ return self._settings.value(self.WINDOWSTATE_KEY, None) @@ -112,8 +112,8 @@ class LeapSettings(object): """ Saves the window state to the settings - @param windowstate: bytearray representing the window state - @type windowstate: bytearray + :param windowstate: bytearray representing the window state + :type windowstate: bytearray """ leap_assert(windowstate, "We need a window state") self._settings.setValue(self.WINDOWSTATE_KEY, windowstate) @@ -122,10 +122,10 @@ class LeapSettings(object): """ Returns a list of enabled services for the given provider - @param provider: provider domain - @type provider: str + :param provider: provider domain + :type provider: str - @rtype: list of str + :rtype: list of str """ leap_assert(len(provider) > 0, "We need a nonempty provider") @@ -140,10 +140,11 @@ class LeapSettings(object): """ Saves the list of enabled services for the given provider - @param provider: provider domain - @type provider: str - @param services: list of services to save - @type services: list of str + :param provider: provider domain + :type provider: str + + :param services: list of services to save + :type services: list of str """ leap_assert(len(provider) > 0, "We need a nonempty provider") @@ -156,7 +157,7 @@ class LeapSettings(object): """ Returns the configured user to remember, None if there isn't one - @rtype: str or None + :rtype: str or None """ return self._settings.value(self.USER_KEY, None) @@ -164,8 +165,8 @@ class LeapSettings(object): """ Saves the user to remember - @param user: user name to remember - @type user: str + :param user: user name to remember + :type user: str """ leap_assert(len(user) > 0, "We cannot save an empty user") self._settings.setValue(self.USER_KEY, user) @@ -174,7 +175,7 @@ class LeapSettings(object): """ Returns the value of the remember selection. - @rtype: bool + :rtype: bool """ return to_bool(self._settings.value(self.REMEMBER_KEY, False)) @@ -182,9 +183,9 @@ class LeapSettings(object): """ Sets wheter the app should remember username and password - @param remember: True if the app should remember username and + :param remember: True if the app should remember username and password, False otherwise - @rtype: bool + :rtype: bool """ leap_assert_type(remember, bool) self._settings.setValue(self.REMEMBER_KEY, remember) @@ -193,7 +194,7 @@ class LeapSettings(object): """ Returns True if the app should automatically login, False otherwise - @rtype: bool + :rtype: bool """ return to_bool(self._settings.value(self.AUTOLOGIN_KEY, False)) @@ -201,8 +202,8 @@ class LeapSettings(object): """ Sets whether the app should automatically login - @param autologin: True if the app should autologin, False otherwise - @type autologin: bool + :param autologin: True if the app should autologin, False otherwise + :type autologin: bool """ leap_assert_type(autologin, bool) self._settings.setValue(self.AUTOLOGIN_KEY, autologin) @@ -211,19 +212,21 @@ class LeapSettings(object): # just one for now def get_properprovider(self): """ - Returns True if there is a properly configured provider + Returns True if there is a properly configured provider. + + .. note:: this assumes only one provider for now. - @rtype: bool + :rtype: bool """ return to_bool(self._settings.value(self.PROPERPROVIDER_KEY, False)) def set_properprovider(self, properprovider): """ - Sets wether the app should automatically login + Sets whether the app should automatically login. - @param properprovider: True if the provider is properly - configured, False otherwise - @type properprovider: bool + :param properprovider: True if the provider is properly configured, + False otherwise. + :type properprovider: bool """ leap_assert_type(properprovider, bool) self._settings.setValue(self.PROPERPROVIDER_KEY, properprovider) diff --git a/src/leap/config/providerconfig.py b/src/leap/config/providerconfig.py index 5aa0cc6e..8f75d4fe 100644 --- a/src/leap/config/providerconfig.py +++ b/src/leap/config/providerconfig.py @@ -68,7 +68,7 @@ class ProviderConfig(BaseConfig): """ Returns the enrollment policy - @rtype: string + :rtype: string """ return self._safe_get_value("enrollment_policy") @@ -82,27 +82,28 @@ class ProviderConfig(BaseConfig): def get_services(self): """ Returns a list with the services supported by the - current provider + current provider. - @rtype: list + :rtype: list """ return self._safe_get_value("services") def get_services_string(self): """ - Returns a string with the services supported by the current provider, - ready to be shown to the user + Returns a string with the services supported by the current + provider, ready to be shown to the user. """ return ", ".join(self.get_services()) def get_ca_cert_path(self, about_to_download=False): """ - Returns the path to the certificate for the current provider + Returns the path to the certificate for the current provider. - @param about_to_download: defines wether we want the path to - download the cert or not. This helps avoid checking if the - cert exists because we are about to write it. - @type about_to_download: bool + :param about_to_download: defines wether we want the path to + download the cert or not. This helps avoid + checking if the cert exists because we + are about to write it. + :type about_to_download: bool """ cert_path = os.path.join(self.get_path_prefix(), @@ -122,8 +123,10 @@ class ProviderConfig(BaseConfig): def provides_eip(self): """ - Returns True if this particular provider has the EIP - service. False otherwise + Returns True if this particular provider has the EIP service, + False otherwise. + + :rtype: bool """ return "openvpn" in self.get_services() diff --git a/src/leap/crypto/srpauth.py b/src/leap/crypto/srpauth.py index ba8ac3f5..9446cee8 100644 --- a/src/leap/crypto/srpauth.py +++ b/src/leap/crypto/srpauth.py @@ -58,8 +58,8 @@ class SRPAuth(QtCore.QObject): """ Constructor for SRPAuth implementation - @param server: Server to which we will authenticate - @type server: str + :param server: Server to which we will authenticate + :type server: str """ QtCore.QObject.__init__(self) @@ -91,11 +91,11 @@ class SRPAuth(QtCore.QObject): Rounds the val to a multiple of 2 and returns the unhexlified value - @param val: hexlified value - @type val: str + :param val: hexlified value + :type val: str - @rtype: binary hex data - @return: unhexlified val + :rtype: binary hex data + :return: unhexlified val """ return binascii.unhexlify(val) \ if (len(val) % 2 == 0) else binascii.unhexlify('0' + val) @@ -104,10 +104,10 @@ class SRPAuth(QtCore.QObject): """ Generates the SRP.User to get the A SRP parameter - @param username: username to login - @type username: str - @param password: password for the username - @type password: str + :param username: username to login + :type username: str + :param password: password for the username + :type password: str """ logger.debug("Authentication preprocessing...") self._srp_user = self._srp.User(username, @@ -125,13 +125,13 @@ class SRPAuth(QtCore.QObject): Might raise SRPAuthenticationError - @param username: username to login - @type username: str - @param password: password for the username - @type password: str + :param username: username to login + :type username: str + :param password: password for the username + :type password: str - @return: salt and B parameters - @rtype: tuple + :return: salt and B parameters + :rtype: tuple """ logger.debug("Starting authentication process...") try: @@ -184,15 +184,15 @@ class SRPAuth(QtCore.QObject): Might throw SRPAuthenticationError - @param salt: salt for the username - @type salt: str - @param B: B SRP parameter - @type B: str - @param username: username for this session - @type username: str + :param salt: salt for the username + :type salt: str + :param B: B SRP parameter + :type B: str + :param username: username for this session + :type username: str - @return: the M2 SRP parameter - @rtype: str + :return: the M2 SRP parameter + :rtype: str """ logger.debug("Processing challenge...") try: @@ -261,8 +261,8 @@ class SRPAuth(QtCore.QObject): Might throw SRPAuthenticationError - @param M2: M2 SRP parameter - @type M2: str + :param M2: M2 SRP parameter + :type M2: str """ logger.debug("Verifying session...") try: @@ -296,10 +296,10 @@ class SRPAuth(QtCore.QObject): Might raise SRPAuthenticationError - @param username: username for this session - @type username: str - @param password: password for this user - @type password: str + :param username: username for this session + :type username: str + :param password: password for this user + :type password: str """ leap_assert(self.get_session_id() is None, "Already logged in") @@ -390,10 +390,10 @@ class SRPAuth(QtCore.QObject): Might raise SRPAuthenticationError - @param username: username for this session - @type username: str - @param password: password for this user - @type password: str + :param username: username for this session + :type username: str + :param password: password for this user + :type password: str """ try: diff --git a/src/leap/crypto/srpregister.py b/src/leap/crypto/srpregister.py index 59aaf257..b9ca16cf 100644 --- a/src/leap/crypto/srpregister.py +++ b/src/leap/crypto/srpregister.py @@ -48,11 +48,11 @@ class SRPRegister(QtCore.QObject): """ Constructor - @param provider_config: provider configuration instance, + :param provider_config: provider configuration instance, properly loaded - @type privider_config: ProviderConfig - @param register_path: webapp path for registering users - @type register_path; str + :type privider_config: ProviderConfig + :param register_path: webapp path for registering users + :type register_path; str """ QtCore.QObject.__init__(self) leap_assert(provider_config, "Please provide a provider") @@ -84,7 +84,7 @@ class SRPRegister(QtCore.QObject): Returns the URI where the register request should be made for the provider - @rtype: str + :rtype: str """ uri = "https://%s:%s/%s/%s" % ( @@ -99,13 +99,13 @@ class SRPRegister(QtCore.QObject): """ Registers a user with the validator based on the password provider - @param username: username to register - @type username: str - @param password: password for this username - @type password: str + :param username: username to register + :type username: str + :param password: password for this username + :type password: str - @rtype: tuple - @rparam: (ok, request) + :rtype: tuple + :rparam: (ok, request) """ salt, verifier = self._srp.create_salted_verification_key( username, diff --git a/src/leap/crypto/tests/fake_provider.py b/src/leap/crypto/tests/fake_provider.py index d533b82b..74a735ff 100755 --- a/src/leap/crypto/tests/fake_provider.py +++ b/src/leap/crypto/tests/fake_provider.py @@ -321,8 +321,8 @@ def get_provider_factory(): * port 8000 for http connections * port 8443 for https connections - @rparam: factory for a site - @rtype: Site instance + :rparam: factory for a site + :rtype: Site instance """ root = Resource() root.putChild("provider.json", File( diff --git a/src/leap/gui/mainwindow.py b/src/leap/gui/mainwindow.py index c9743f95..ccf97672 100644 --- a/src/leap/gui/mainwindow.py +++ b/src/leap/gui/mainwindow.py @@ -72,12 +72,12 @@ class MainWindow(QtGui.QMainWindow): """ Constructor for the client main window - @param standalone: Set to true if the app should use configs + :param standalone: Set to true if the app should use configs inside its pwd - @type standalone: bool - @param bypass_checks: Set to true if the app should bypass + :type standalone: bool + :param bypass_checks: Set to true if the app should bypass first round of checks for CA certificates at bootstrap - @type bypass_checks: bool + :type bypass_checks: bool """ QtGui.QMainWindow.__init__(self) @@ -278,8 +278,8 @@ class MainWindow(QtGui.QMainWindow): """ Callback for the new updates event - @param req: Request type - @type req: leap.common.events.events_pb2.SignalRequest + :param req: Request type + :type req: leap.common.events.events_pb2.SignalRequest """ self.new_updates.emit(req) @@ -482,7 +482,7 @@ class MainWindow(QtGui.QMainWindow): """ Returns the available providers based on the file structure - @rtype: list + :rtype: list """ # TODO: check which providers have a valid certificate among @@ -503,7 +503,7 @@ class MainWindow(QtGui.QMainWindow): """ Returns True if there are no configured providers. False otherwise - @rtype: bool + :rtype: bool """ has_provider_on_disk = len(self._configured_providers()) != 0 is_proper_provider = self._settings.get_properprovider() @@ -519,8 +519,8 @@ class MainWindow(QtGui.QMainWindow): """ Sets the status label at the login stage to status - @param status: status message - @type status: str + :param status: status message + :type status: str """ if error: status = "%s" % (status,) @@ -530,8 +530,8 @@ class MainWindow(QtGui.QMainWindow): """ Sets the status label at the VPN stage to status - @param status: status message - @type status: str + :param status: status message + :type status: str """ self._vpn_systray.setToolTip(status) if error: @@ -542,8 +542,8 @@ class MainWindow(QtGui.QMainWindow): """ Enables or disables all the login widgets - @param enabled: wether they should be enabled or not - @type enabled: bool + :param enabled: wether they should be enabled or not + :type enabled: bool """ self.ui.lnUser.setEnabled(enabled) self.ui.lnPassword.setEnabled(enabled) @@ -575,9 +575,9 @@ class MainWindow(QtGui.QMainWindow): self._provider_config instance with it and starts the second part of the bootstrapping sequence - @param data: result from the last stage of the + :param data: result from the last stage of the run_provider_select_checks - @type data: dict + :type data: dict """ if data[self._provider_bootstrapper.PASSED_KEY]: provider = self.ui.cmbProviders.currentText() @@ -708,7 +708,7 @@ class MainWindow(QtGui.QMainWindow): """ Returns the socket and port to be used for VPN - @rtype: tuple (str, str) (host, port) + :rtype: tuple (str, str) (host, port) """ # TODO: make this properly multiplatform @@ -801,8 +801,8 @@ class MainWindow(QtGui.QMainWindow): """ Given a status step from the VPN thread, set the icon properly - @param status: status step - @type status: str + :param status: status step + :type status: str """ selected_pixmap = self.ERROR_ICON tray_message = self.tr("Encryption is OFF") diff --git a/src/leap/gui/wizard.py b/src/leap/gui/wizard.py index 33c3ed0c..ad45dd8c 100644 --- a/src/leap/gui/wizard.py +++ b/src/leap/gui/wizard.py @@ -55,14 +55,14 @@ class Wizard(QtGui.QWizard): """ Constructor for the main Wizard. - @param checker: Checker thread that the wizard should use. - @type checker: CheckerThread - @param standalone: If True, the application is running as standalone + :param checker: Checker thread that the wizard should use. + :type checker: CheckerThread + :param standalone: If True, the application is running as standalone and the wizard should display some messages according to this. - @type standalone: bool - @param bypass_checks: Set to true if the app should bypass + :type standalone: bool + :param bypass_checks: Set to true if the app should bypass first round of checks for CA certificates at bootstrap - @type bypass_checks: bool + :type bypass_checks: bool """ QtGui.QWizard.__init__(self) @@ -184,15 +184,15 @@ class Wizard(QtGui.QWizard): """ Performs basic password checks to avoid really easy passwords. - @param username: username provided at the registrarion form - @type username: str - @param password: password from the registration form - @type password: str - @param password2: second password from the registration form - @type password: str + :param username: username provided at the registrarion form + :type username: str + :param password: password from the registration form + :type password: str + :param password2: second password from the registration form + :type password: str - @return: returns True if all the checks pass, False otherwise - @rtype: bool + :return: returns True if all the checks pass, False otherwise + :rtype: bool """ message = None @@ -266,8 +266,8 @@ class Wizard(QtGui.QWizard): """ Sets the status label in the registration page to status - @param status: status message to display, can be HTML - @type status: str + :param status: status message to display, can be HTML + :type status: str """ if error: status = "%s" % (status,) @@ -321,17 +321,17 @@ class Wizard(QtGui.QWizard): """ Checks a task and completes a page if specified - @param data: data as it comes from the bootstrapper thread for + :param data: data as it comes from the bootstrapper thread for a specific check - @type data: dict - @param label: label that displays the status icon for a + :type data: dict + :param label: label that displays the status icon for a specific check that corresponds to the data - @type label: QtGui.QLabel - @param complete: if True, it completes the page specified, + :type label: QtGui.QLabel + :param complete: if True, it completes the page specified, which must be of type WizardPage - @type complete: bool - @param complete_page: page id to complete - @type complete_page: int + :type complete: bool + :param complete_page: page id to complete + :type complete_page: int """ passed = data[self._provider_bootstrapper.PASSED_KEY] error = data[self._provider_bootstrapper.ERROR_KEY] @@ -450,10 +450,10 @@ class Wizard(QtGui.QWizard): Adds the service to the state if the state is checked, removes it otherwise - @param service: service to handle - @type service: str - @param state: state of the checkbox - @type state: int + :param service: service to handle + :type service: str + :param state: state of the checkbox + :type state: int """ if state == QtCore.Qt.Checked: self._selected_services = \ diff --git a/src/leap/platform_init/locks.py b/src/leap/platform_init/locks.py index f1672d8e..e5b392a3 100644 --- a/src/leap/platform_init/locks.py +++ b/src/leap/platform_init/locks.py @@ -74,7 +74,7 @@ if platform_init.IS_UNIX: """ Tries to get a lock, returning True if successful - @rtype: bool + :rtype: bool """ self._fd = os.open(self.path, os.O_CREAT | os.O_RDWR) @@ -98,7 +98,7 @@ if platform_init.IS_UNIX: Returns True if the pid in the pidfile is ours. - @rtype: bool + :rtype: bool """ gotit, pid = self._get_lock_and_pid() return pid == os.getpid() @@ -108,7 +108,7 @@ if platform_init.IS_UNIX: Tries to get a lock over the file. Returns (locked, pid) tuple. - @rtype: tuple + :rtype: tuple """ if self._get_lock(): @@ -192,7 +192,7 @@ if platform_init.IS_WIN: Returns True, pid if there is only one pidfile with the expected base path - @rtype: tuple + :rtype: tuple """ pidfiles = glob.glob(self.LOCKBASE + '-*') if len(pidfiles) == 1: @@ -205,7 +205,7 @@ if platform_init.IS_WIN: """ Returns the pid of the locking process - @rtype: int + :rtype: int """ # XXX assert there is only one? _, pid = self._is_one_pidfile() @@ -238,7 +238,7 @@ if platform_init.IS_WIN: Returns True if the pid in the pidfile is ours. - @rtype: bool + :rtype: bool """ _, pid = self._is_one_pidfile() return pid == self.pid @@ -248,7 +248,7 @@ if platform_init.IS_WIN: Writes the port for windows control to the pidfile folder Returns True if successful. - @rtype: bool + :rtype: bool """ if not self.locked_by_us: logger.warning("Tried to write control port to a " @@ -264,7 +264,7 @@ if platform_init.IS_WIN: Reads control port of the main instance from the port file in the pidfile dir - @rtype: int + :rtype: int """ pid = self.get_pid() port_file = os.path.join(self.LOCKBASE + "-%s" % pid, "port") @@ -288,7 +288,7 @@ def we_are_the_one_and_only(): If we came later, send a raise signal to the main instance of the application - @rtype: bool + :rtype: bool """ _sys = platform.system() diff --git a/src/leap/services/eip/eipbootstrapper.py b/src/leap/services/eip/eipbootstrapper.py index 19b74856..af13ab8c 100644 --- a/src/leap/services/eip/eipbootstrapper.py +++ b/src/leap/services/eip/eipbootstrapper.py @@ -73,8 +73,8 @@ class EIPBootstrapper(QtCore.QObject): """ Downloads the EIP config for the given provider - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._provider_config, @@ -137,8 +137,8 @@ class EIPBootstrapper(QtCore.QObject): """ Downloads the EIP client certificate for the given provider - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._provider_config, "We need a provider configuration!") leap_assert(self._eip_config, "We need an eip configuration!") @@ -216,8 +216,8 @@ class EIPBootstrapper(QtCore.QObject): """ Starts the checks needed for a new eip setup - @param provider_config: Provider configuration - @type provider_config: ProviderConfig + :param provider_config: Provider configuration + :type provider_config: ProviderConfig """ leap_assert(provider_config, "We need a provider config!") leap_assert_type(provider_config, ProviderConfig) diff --git a/src/leap/services/eip/providerbootstrapper.py b/src/leap/services/eip/providerbootstrapper.py index f5559143..734d3867 100644 --- a/src/leap/services/eip/providerbootstrapper.py +++ b/src/leap/services/eip/providerbootstrapper.py @@ -62,9 +62,9 @@ class ProviderBootstrapper(QtCore.QObject): """ Constructor for provider bootstrapper object - @param bypass_checks: Set to true if the app should bypass + :param bypass_checks: Set to true if the app should bypass first round of checks for CA certificates at bootstrap - @type bypass_checks: bool + :type bypass_checks: bool """ QtCore.QObject.__init__(self) @@ -84,8 +84,8 @@ class ProviderBootstrapper(QtCore.QObject): """ Checks that the name resolution for the provider name works - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._domain, "Cannot check DNS without a domain") @@ -115,8 +115,8 @@ class ProviderBootstrapper(QtCore.QObject): Checks that https is working and that the provided certificate checks out - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._domain, "Cannot check HTTPS without a domain") @@ -154,8 +154,8 @@ class ProviderBootstrapper(QtCore.QObject): """ Downloads the provider.json defition - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._domain, "Cannot download provider info without a domain") @@ -211,16 +211,15 @@ class ProviderBootstrapper(QtCore.QObject): """ Populates the check queue - @param checker: checker thread to be used to run this check - @type checker: CheckerThread - @param domain: domain to check - @type domain: str - @param download_if_needed: if True, makes the checks do not - overwrite already downloaded data - @type download_if_needed: bool + :param checker: checker thread to be used to run this check + :type checker: CheckerThread + :param domain: domain to check + :type domain: str + :param download_if_needed: if True, makes the checks do not overwrite already downloaded data + :type download_if_needed: bool - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(domain and len(domain) > 0, "We need a domain!") @@ -238,7 +237,7 @@ class ProviderBootstrapper(QtCore.QObject): Returns False if the certificate already exists for the given provider. True otherwise - @rtype: bool + :rtype: bool """ leap_assert(self._provider_config, "We need a provider config!") @@ -252,8 +251,8 @@ class ProviderBootstrapper(QtCore.QObject): """ Downloads the CA cert that is going to be used for the api URL - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._provider_config, "Cannot download the ca cert " @@ -310,8 +309,8 @@ class ProviderBootstrapper(QtCore.QObject): Checks the CA cert fingerprint against the one provided in the json definition - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._provider_config, "Cannot check the ca cert " "without a provider config!") @@ -362,8 +361,8 @@ class ProviderBootstrapper(QtCore.QObject): Tries to make an API call with the downloaded cert and checks if it validates against it - @return: True if the checks passed, False otherwise - @rtype: bool + :return: True if the checks passed, False otherwise + :rtype: bool """ leap_assert(self._provider_config, "Cannot check the ca cert " "without a provider config!") @@ -403,13 +402,13 @@ class ProviderBootstrapper(QtCore.QObject): provider_config, download_if_needed=False): """ - Starts the checks needed for a new provider setup + Starts the checks needed for a new provider setup. - @param provider_config: Provider configuration - @type provider_config: ProviderConfig - @param download_if_needed: if True, makes the checks do not - overwrite already downloaded data - @type download_if_needed: bool + :param provider_config: Provider configuration + :type provider_config: ProviderConfig + + :param download_if_needed: if True, makes the checks do not overwrite already downloaded data. + :type download_if_needed: bool """ leap_assert(provider_config, "We need a provider config!") leap_assert_type(provider_config, ProviderConfig) diff --git a/src/leap/services/eip/udstelnet.py b/src/leap/services/eip/udstelnet.py index a47c24f4..e6c82350 100644 --- a/src/leap/services/eip/udstelnet.py +++ b/src/leap/services/eip/udstelnet.py @@ -40,7 +40,6 @@ class UDSTelnet(telnetlib.Telnet): The optional second argument is the port number, which defaults to the standard telnet port (23). - Don't try to reopen an already connected instance. """ self.eof = 0 diff --git a/src/leap/services/eip/vpn.py b/src/leap/services/eip/vpn.py index 9d838609..af1febe6 100644 --- a/src/leap/services/eip/vpn.py +++ b/src/leap/services/eip/vpn.py @@ -85,8 +85,8 @@ class VPN(QtCore.QThread): """ Returns wether this thread should quit - @rtype: bool - @return: True if the thread should terminate itself, Flase otherwise + :rtype: bool + :return: True if the thread should terminate itself, Flase otherwise """ QtCore.QMutexLocker(self._should_quit_lock) return self._should_quit @@ -117,15 +117,15 @@ class VPN(QtCore.QThread): """ Launches OpenVPN and starts the thread to watch its output - @param eipconfig: eip configuration object - @type eipconfig: EIPConfig - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix + :param eipconfig: eip configuration object + :type eipconfig: EIPConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + :param socket_port: either string "unix" if it's a unix socket, or port otherwise - @type socket_port: str + :type socket_port: str """ leap_assert(eipconfig, "We need an eip config") leap_assert_type(eipconfig, EIPConfig) @@ -196,7 +196,7 @@ class VPN(QtCore.QThread): """ Looks for openvpn instances running - @rtype: process + :rtype: process """ openvpn_process = None for p in psutil.process_iter(): @@ -217,7 +217,7 @@ class VPN(QtCore.QThread): """ Checks if VPN is already running and tries to stop it - @return: True if stopped, False otherwise + :return: True if stopped, False otherwise """ process = self._get_openvpn_process() @@ -253,11 +253,11 @@ class VPN(QtCore.QThread): def _connect(self, socket_host, socket_port): """ Connects to the specified socket_host socket_port - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + :param socket_port: either string "unix" if it's a unix socket, or port otherwise - @type socket_port: str + :type socket_port: str """ try: self._tn = UDSTelnet(socket_host, socket_port) @@ -291,12 +291,12 @@ class VPN(QtCore.QThread): Sends a command to the telnet connection and reads until END is reached - @param command: command to send - @type command: str - @param until: byte delimiter string for reading command output - @type until: byte str - @return: response read - @rtype: list + :param command: command to send + :type command: str + :param until: byte delimiter string for reading command output + :type until: byte str + :return: response read + :rtype: list """ leap_assert(self._tn, "We need a tn connection!") try: @@ -315,9 +315,9 @@ class VPN(QtCore.QThread): Parses the output of the state command and emits state_changed signal when the state changes - @param output: list of lines that the state command printed as + :param output: list of lines that the state command printed as its output - @type output: list + :type output: list """ for line in output: stripped = line.strip() @@ -345,9 +345,9 @@ class VPN(QtCore.QThread): Parses the output of the status command and emits status_changed signal when the status changes - @param output: list of lines that the status command printed + :param output: list of lines that the status command printed as its output - @type output: list + :type output: list """ tun_tap_read = "" tun_tap_write = "" diff --git a/src/leap/services/eip/vpnlaunchers.py b/src/leap/services/eip/vpnlaunchers.py index 3d36736d..540bc45e 100644 --- a/src/leap/services/eip/vpnlaunchers.py +++ b/src/leap/services/eip/vpnlaunchers.py @@ -67,18 +67,18 @@ class VPNLauncher: """ Returns the platform dependant vpn launching command - @param eipconfig: eip configuration object - @type eipconfig: EIPConfig - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix + :param eipconfig: eip configuration object + :type eipconfig: EIPConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + :param socket_port: either string "unix" if it's a unix socket, or port otherwise - @type socket_port: str + :type socket_port: str - @return: A VPN command ready to be launched - @rtype: list + :return: A VPN command ready to be launched + :rtype: list """ return [] @@ -89,10 +89,10 @@ class VPNLauncher: This is mainly used for setting LD_LIBRARY_PATH to the correct path when distributing a standalone client - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig - @rtype: dict + :rtype: dict """ return {} @@ -148,18 +148,21 @@ class LinuxVPNLauncher(VPNLauncher): Might raise VPNException. - @param eipconfig: eip configuration object - @type eipconfig: EIPConfig - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix - socket, or port otherwise - @type socket_port: str + :param eipconfig: eip configuration object + :type eipconfig: EIPConfig + + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig + + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + + :param socket_port: either string "unix" if it's a unix + socket, or port otherwise + :type socket_port: str - @return: A VPN command ready to be launched - @rtype: list + :return: A VPN command ready to be launched + :rtype: list """ leap_assert(eipconfig, "We need an eip config") leap_assert_type(eipconfig, EIPConfig) @@ -263,10 +266,10 @@ class LinuxVPNLauncher(VPNLauncher): This is mainly used for setting LD_LIBRARY_PATH to the correct path when distributing a standalone client - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig - @rtype: dict + :rtype: dict """ leap_assert(providerconfig, "We need a provider config") leap_assert_type(providerconfig, ProviderConfig) @@ -300,18 +303,21 @@ class DarwinVPNLauncher(VPNLauncher): Might raise VPNException. - @param eipconfig: eip configuration object - @type eipconfig: EIPConfig - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix - socket, or port otherwise - @type socket_port: str + :param eipconfig: eip configuration object + :type eipconfig: EIPConfig + + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig + + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + + :param socket_port: either string "unix" if it's a unix + socket, or port otherwise + :type socket_port: str - @return: A VPN command ready to be launched - @rtype: list + :return: A VPN command ready to be launched + :rtype: list """ leap_assert(eipconfig, "We need an eip config") leap_assert_type(eipconfig, EIPConfig) @@ -405,10 +411,10 @@ class DarwinVPNLauncher(VPNLauncher): This is mainly used for setting LD_LIBRARY_PATH to the correct path when distributing a standalone client - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig - @rtype: dict + :rtype: dict """ return {"DYLD_LIBRARY_PATH": os.path.join( providerconfig.get_path_prefix(), @@ -431,18 +437,18 @@ class WindowsVPNLauncher(VPNLauncher): Might raise VPNException. - @param eipconfig: eip configuration object - @type eipconfig: EIPConfig - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig - @param socket_host: either socket path (unix) or socket IP - @type socket_host: str - @param socket_port: either string "unix" if it's a unix + :param eipconfig: eip configuration object + :type eipconfig: EIPConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig + :param socket_host: either socket path (unix) or socket IP + :type socket_host: str + :param socket_port: either string "unix" if it's a unix socket, or port otherwise - @type socket_port: str + :type socket_port: str - @return: A VPN command ready to be launched - @rtype: list + :return: A VPN command ready to be launched + :rtype: list """ leap_assert(eipconfig, "We need an eip config") leap_assert_type(eipconfig, EIPConfig) @@ -514,10 +520,10 @@ class WindowsVPNLauncher(VPNLauncher): This is mainly used for setting LD_LIBRARY_PATH to the correct path when distributing a standalone client - @param providerconfig: provider specific configuration - @type providerconfig: ProviderConfig + :param providerconfig: provider specific configuration + :type providerconfig: ProviderConfig - @rtype: dict + :rtype: dict """ return {} diff --git a/src/leap/util/checkerthread.py b/src/leap/util/checkerthread.py index 47a96ec5..02aa333f 100644 --- a/src/leap/util/checkerthread.py +++ b/src/leap/util/checkerthread.py @@ -48,10 +48,10 @@ class CheckerThread(QtCore.QThread): def get_should_quit(self): """ - Returns wether this thread should quit + Returns whether this thread should quit - @rtype: bool - @return: True if the thread should terminate itself, Flase otherwise + :return: True if the thread should terminate itself, Flase otherwise + :rtype: bool """ QtCore.QMutexLocker(self._should_quit_lock) @@ -78,8 +78,8 @@ class CheckerThread(QtCore.QThread): """ Adds a list of checks to the ones being executed - @param checks: check functions to perform - @type checkes: list + :param checks: check functions to perform + :type checkes: list """ with QtCore.QMutexLocker(self._checks_lock): self._checks += checks diff --git a/src/leap/util/privilege_policies.py b/src/leap/util/privilege_policies.py index e74c4d33..10224bcd 100644 --- a/src/leap/util/privilege_policies.py +++ b/src/leap/util/privilege_policies.py @@ -33,7 +33,7 @@ def is_missing_policy_permissions(): platform, or if the policy checker exists but it cannot find the appropriate policy mechanisms in place. - @rtype: bool + :rtype: bool """ _system = platform.system() platform_checker = _system + "PolicyChecker" @@ -60,7 +60,7 @@ class PolicyChecker: Returns True if we could not find any policy mechanisms that are defined to be in used for this particular platform. - @rtype: bool + :rtype: bool """ return True @@ -77,6 +77,6 @@ class LinuxPolicyChecker(PolicyChecker): Returns True if we could not find the appropriate policykit file in place - @rtype: bool + :rtype: bool """ return not os.path.isfile(self.LINUX_POLKIT_FILE) diff --git a/src/leap/util/request_helpers.py b/src/leap/util/request_helpers.py index 019ff353..e06dabb8 100644 --- a/src/leap/util/request_helpers.py +++ b/src/leap/util/request_helpers.py @@ -32,10 +32,10 @@ def get_content(request): property/function or from content, in that order. Also returns the mtime for that content if available - @param request: request as it is given by requests - @type request: Response + :param request: request as it is given by requests + :type request: Response - @rtype: tuple (contents, mtime) + :rtype: tuple (contents, mtime) """ contents = "" -- cgit v1.2.3 From e6b7d52d827109d6fc8d79a28e8d46964e1ad94c Mon Sep 17 00:00:00 2001 From: kali Date: Tue, 7 May 2013 23:03:24 +0900 Subject: fix pyqt references --- docs/checklist_for_leap_client_release.wiki | 2 +- docs/dev/internationalization.rst | 22 +++++++++------------- docs/dev/resources.rst | 4 ++-- docs/pkg/debian.rst | 4 ++-- pkg/scripts/leap_client_bootstrap.sh | 2 +- 5 files changed, 15 insertions(+), 19 deletions(-) diff --git a/docs/checklist_for_leap_client_release.wiki b/docs/checklist_for_leap_client_release.wiki index 5abced80..d3bdf1ee 100644 --- a/docs/checklist_for_leap_client_release.wiki +++ b/docs/checklist_for_leap_client_release.wiki @@ -4,7 +4,7 @@ * [ ] all rc-critical closed! * [ ] all bbots green * [ ] uploaded translations: make translations - * [ ] re-generate pyqt resources + * [ ] re-generate pyside resources * [ ] update docs * [ ] CREDITS diff --git a/docs/dev/internationalization.rst b/docs/dev/internationalization.rst index 1a9af0be..8c584fdd 100644 --- a/docs/dev/internationalization.rst +++ b/docs/dev/internationalization.rst @@ -6,7 +6,7 @@ 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 +Translating the LEAP Client PySide Application -------------------------------------------- .. raw:: html @@ -32,7 +32,7 @@ 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 `_. +Refer to `pyside documentation `_. tl;dr;:: @@ -40,15 +40,11 @@ tl;dr;:: 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(, , ) +.. 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(, , ) .. Note about this: there seems to be some problems with the .tr method @@ -59,9 +55,9 @@ If you have to translate something that it is not a ``QObject``, use the magic l For i18n maintainers ^^^^^^^^^^^^^^^^^^^^ -You need ``pylupdate4`` and ``lrelease`` for these steps. To get it, in debian:: +You need ``pyside-lupdate`` and ``lrelease`` for these steps. To get it, in debian:: - $ apt-get install pyqt4-dev-tools qt4-linguist-tools + $ apt-get install pyside-tools qt4-linguist-tools If you do not already have it, install the ``transifex-client`` from the cheese shop:: diff --git a/docs/dev/resources.rst b/docs/dev/resources.rst index 7cfa2b70..e68649a1 100644 --- a/docs/dev/resources.rst +++ b/docs/dev/resources.rst @@ -1,7 +1,7 @@ .. _resources: -PyQt Resource files -=================== +PySide Resource files +===================== Compiling resource/ui files --------------------------- diff --git a/docs/pkg/debian.rst b/docs/pkg/debian.rst index e98032a5..204d4073 100644 --- a/docs/pkg/debian.rst +++ b/docs/pkg/debian.rst @@ -10,9 +10,9 @@ Dependencies ------------ * ``openvpn`` -* ``python-qt4`` +* ``python-pyside`` * ``python-crypto`` -* ``python setuptools`` +* ``python-setuptools`` * ``python-requests`` * ``python-openssl`` diff --git a/pkg/scripts/leap_client_bootstrap.sh b/pkg/scripts/leap_client_bootstrap.sh index 6c302d3f..dcde64f9 100644 --- a/pkg/scripts/leap_client_bootstrap.sh +++ b/pkg/scripts/leap_client_bootstrap.sh @@ -38,7 +38,7 @@ pip install -e 'git://leap.se/leap_client@develop#egg=leap-client' cd leap-client-testbuild -# symlink the pyqt libraries to the system libs +# symlink the pyside libraries to the system libs ./src/leap-client/pkg/postmkvenv.sh echo "${cc_green}leap-client installed! =)" -- cgit v1.2.3