Merge pull request #11 from NBISweden/docs

Documentation

docs/.gitignore

@@ -0,0 +1,8 @@
+# =====================================
+# Sphinx documentation
+# =====================================
+_build/
+static/*.key
+
+# These should be generated every time
+lega.utils/

docs/CONTRIBUTING.rst

@@ -0,0 +1,172 @@
+.. role:: bolditalic
+    :class: bolditalic
+
+=======================
+Contributing guidelines
+=======================
+
+We thank you in advance |thumbup| |tada| for taking the time to
+contribute, whether with *code* or with *ideas*, to the Local EGA cryptor
+project.
+
+------------------------
+AGILE project management
+------------------------
+
+We use *Zenhub*, the Agile project management within Github.
+
+You should first `install it`_ if you want to contribute or just follow the project progress.
+You can also use the `Zenhub app`_ if you wish.
+
+In short, the `AGILE method`_ helps developers organize themselves:
+
+* They decide about the tasks (not the managers)
+* Main Tasks should be divided into smaller manageable ones. The big
+  tasks are called *Epics*.
+* We have a given period (called Sprint) to work on a chosen
+  task. Here, a Sprint spans across 2 weeks.
+* We review the work done at the end of the Sprint, closing issues or
+  pushing them into the next Sprint. Ideally, they are sub-divided in
+  case they encounter obstacles.
+* We have a short meeting every weekday at 9:30 AM. We call it a
+  *standup* and we use it to keep everyone on point, and identify
+  quickly blockers. It's not a lengthy discussion. We ask:
+
+  - What did you get done yesterday (or last week, last month, etc.)?
+  - What are you working on now?
+  - What isn’t going well, and on what could you use help?
+
+---------
+Procedure
+---------
+
+1. Create an issue on Github, and talk to the team members on the NBIS
+   local-ega Slack channel. You can alternatively pick one already
+   created.
+
+.. note::
+   Contact `Jonas Hagberg`_ to request access if you are not part of that channel already.
+
+
+2. Assign yourself to that issue.
+
+#. Discussions on how to proceed about that issue take place in the
+   comment section on that issue, beforehand.
+
+   The keyword here is *beforehand*. It is usually a good idea to talk
+   about it first. Somebody might have already some pieces in place,
+   we avoid unnecessary work duplication and a waste of time and
+   effort.
+
+#. Work on it (on a fork, or on a separate branch) as you wish. That's
+   what ``git`` is good for. This GitHub repository follows
+   the `coding guidelines from NBIS`_.
+
+   Name your branch as you wish and prefix the name with:
+
+   * ``feature/`` if it is a code feature
+   * ``hotfix/`` if you are fixing an urgent bug
+
+   Use comments in your code, choose variable and function names that
+   clearly show what you intend to implement.
+
+   Use `git rebase -i`_ in
+   order to rewrite your history, and have meaningful commits.  That
+   way, we avoid the 'Typo', 'Work In Progress (WIP)', or
+   'Oops...forgot this or that' commits.
+
+   Limit the first line of your git commits to 72 characters or less.
+
+
+#. Create a Pull Request (PR), so that your code is reviewed by the
+   admins on this repository.
+
+   That PR should be connected to the issue you are working on.
+   Moreover, the PR:
+
+   - should use ``Estimate=1``,
+   - should be connected to:
+
+     * an ``Epic``,
+     * a ``Milestone`` and
+     * a ``User story``
+     * ... or several.
+
+   N.B: Pull requests are done to the ``dev`` branch. PRs to ``master`` are rejected.
+
+#. Selecting a review goes as follows: Pick one *main* reviewer.  It
+   is usually one that you had discussions with, and is somehow
+   connected to that issue. If this is not the case, pick several reviewers.
+
+   Note that, in turn, the main reviewer might ask another reviewer
+   for help. The approval of all reviewers is compulsory in order to
+   merge the PR. Moreover, the main reviewer is the one merging the
+   PR, not you.
+
+   Find more information on the `NBIS reviewing guidelines`_.
+
+
+#. It is possible that your PR requires changes (because it creates
+   conflicts, doesn't pass the integrated tests or because some parts
+   should be rewritten in a cleaner manner, or because it does not
+   follow the standards, or you're requesting the wrong branch to pull
+   your code, etc...) In that case, a reviewer will request changes
+   and describe them in the comment section of the PR.
+
+   You then update your branch with new commits. We will see the PR
+   changes faster if you ping the reviewer in the slack channel.
+
+   Note that the comments *in the PR* are not used to discuss the
+   *how* and *why* of that issue. These discussions are not about the
+   issue itself but about *a solution* to that issue.
+
+   Recall that discussions about the issue are good and prevent
+   duplicated or wasted efforts, but they take place in the comment
+   section of the related issue (see point 4), not in the PR.
+
+   Essentially, we don't want to open discussions when the work is
+   done, and there is no recourse, such that it's either accept or
+   reject. We think we can do better than that, and introduce a finer
+   grained acceptance, by involving *beforehand* discussions so that
+   everyone is on point.
+
+
+
+-------------------
+Did you find a bug?
+-------------------
+
+* Ensure that the bug was not already reported by `searching under Issues`_.
+
+* Do :bolditalic:`not` file it as a plain GitHub issue (we use the
+  issue system for our internal tasks (see Zenhub)).  If you're unable
+  to find an (open) issue addressing the problem, `open a new one`_.
+  Be sure to prefix the issue title with **[BUG]** and to include:
+
+  - a *clear* description,
+  - as much relevant information as possible, and
+  - a *code sample* or an (executable) *test case* demonstrating the expected behaviour that is not occurring.
+
+* If possible, use the following `template to report a bug`_.
+
+.. todo:: Make that template
+
+
+----
+
+| Thanks again,
+| /NBIS System Developers
+
+.. _Zenhub: https://www.zenhub.com
+.. _install it: https://www.zenhub.com/extension
+.. _Zenhub app: https://app.zenhub.com
+.. _AGILE method: https://www.zenhub.com/blog/how-to-use-github-agile-project-management
+.. _Jonas Hagberg: https://nbis.se/about/staff/jonas-hagberg/
+.. _coding guidelines from NBIS: https://github.com/NBISweden/development-guidelines
+.. _git rebase -i: https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
+.. _NBIS reviewing guidelines: https://github.com/NBISweden/development-guidelines#how-we-do-code-reviews
+.. _searching under Issues: https://github.com/NBISweden/LocalEGA-cryptor/issues?utf8=%E2%9C%93&q=is%3Aissue%20label%3Abug%20%5BBUG%5D%20in%3Atitle
+.. _open a new one: https://github.com/NBISweden/LocalEGA-cryptor/issues/new?title=%5BBUG%5D
+.. _template to report a bug: todo
+.. |tada| unicode:: U+1f389
+.. |thumbup| unicode:: U+1f44d

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = python -msphinx
+SPHINXPROJ    = LocalEGA-cryptor
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/code.rst

@@ -0,0 +1,38 @@
+--------------
+Python Modules
+--------------
+
+.. automodule:: legacryptor
+   :members:
+   :synopsis: The lega package contains code to start a *Local EGA cryptor*.
+
+.. autosummary::
+
+    legacryptor.cli
+    legacryptor.crypt4gh
+    legacryptor.pubring
+    legacryptor.exceptions
+
+************
+Command Line
+************
+
+.. automodule:: legacryptor.cli
+   :members:
+
+
+********
+Crypt4gh
+********
+
+.. automodule:: legacryptor.crypt4gh
+   :members: Header, encrypt, get_header, decrypt, reencrypt, get_key_id, header_to_records
+
+************
+Pubring
+************
+
+.. automodule:: legacryptor.pubring
+   :members:
+
+:ref:`genindex` | :ref:`modindex`

docs/conf.py

@@ -0,0 +1,151 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+import os
+import sys
+import datetime
+from unittest.mock import MagicMock
+
+# Get the project root dir, which is the parent dir of this
+#sys.path.insert(0, os.path.dirname(os.getcwd()))
+sys.path.insert(0, os.path.abspath('..'))
+#print('PYTHONPATH =', sys.path)
+
+import legacryptor
+
+# -- General configuration ------------------------------------------------
+
+class Mock(MagicMock):
+    @classmethod
+    def __getattr__(cls, name):
+        return MagicMock()
+
+
+# Some modules need to be mocked
+MOCK_MODULES = ['cryptography.hazmat.primitives.ciphers', 'cryptography.hazmat.backends',
+                'yaml', 'terminaltables', 'pgpy', 'docopt', 'cryptography.hazmat']
+sys.modules.update((mod_name, Mock()) for mod_name in MOCK_MODULES)
+
+# 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',
+              'sphinx.ext.autosummary',
+              'sphinx.ext.coverage',
+              'sphinx.ext.ifconfig',
+              'sphinx.ext.viewcode',
+              'sphinx.ext.githubpages',
+              'sphinx.ext.todo',
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['templates']
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+# source_suffix = ['.rst', '.md']
+source_suffix = '.rst'
+
+# The master toctree document.
+master_doc = 'index'
+
+# Get current year
+current_year = str(datetime.date.today().year)
+
+# General information about the project.
+project = 'LocalEGA GA4GH cryptor'
+copyright = f'{current_year}, NBIS System Developers'
+author = 'NBIS System Developers'
+
+# 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 = str(legacryptor.__version__)
+# The full version, including alpha/beta/rc tags.
+release = str(legacryptor.__version__)
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = None
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This patterns also effect to html_static_path and html_extra_path
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+autosummary_generate = True
+
+# -- Options for HTML output ----------------------------------------------
+
+html_title = 'NBIS LocalEGA GA4GH cryptor'
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+#html_theme = 'alabaster'
+# html_theme_options = {
+#     'fixed_sidebar': True,
+#     'show_powered_by': False,
+#     #'badge_branch': 'dev',
+#     'github_repo': 'https://github.com/NBISweden/LocalEGA',
+#     'github_button': True,
+# }
+
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'collapse_navigation': True,
+    'sticky_navigation': True,
+    #'navigation_depth': 4,
+    'display_version': True,
+    'prev_next_buttons_location': 'bottom',
+}
+
+# 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']
+
+# Custom sidebar templates, must be a dictionary that maps document names
+# to template names.
+#
+# This is required for the alabaster theme
+# refs: http://alabaster.readthedocs.io/en/latest/installation.html#sidebars
+html_sidebars = {
+    '**': [
+        #'about.html',
+        #'navigation.html',
+        #'relations.html',  # needs 'show_related': True theme option to display
+        #'searchbox.html',
+        #'donate.html',
+    ]
+}
+
+
+today_fmt = '%B %d, %Y'
+
+def setup(app):
+    app.add_stylesheet('custom.css')
+
+# -- Other stuff ----------------------------------------------------------
+htmlhelp_basename = 'LocalEGA-cryptor'
+latex_elements = {}
+latex_documents = [ (master_doc, 'LocalEGA-cryptor.tex', 'Local EGA cryptor', 'NBIS System Developers', 'manual') ]
+man_pages = [ (master_doc, 'localega', 'Local EGA', [author], 1) ]
+texinfo_documents = [ (master_doc, 'LocalEGA-cryptor', 'Local EGA cryptor', author, 'LocalEGA cryptor', 'GA4GH cryptographic tools', 'Miscellaneous') ]