Merge branch 'add_doc' into 'master'

add documentation

See merge request !2

doc/conf.py

+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+#
+# Orange3 Example Add-on documentation build configuration file, created by
+# sphinx-quickstart on Fri Aug 21 11:28:31 2015.
+#
+# 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
+import 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('.'))
+project = u'tomoscan'
+
+
+# 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',
+    'nbsphinx',
+]
+
+# 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']
+
+# The encoding of source files.
+#source_encoding = 'utf-8-sig'
+
+# The master toctree document.
+master_doc = 'index'
+
+# General information about the project.
+project = 'tomoscan'
+copyright = '2016-2019, ESRF'
+author = 'ESRF'
+
+# 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.1'
+# The full version, including alpha/beta/rc tags.
+release = '0.1'
+
+# 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
+
+# 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', '**.ipynb_checkpoints']
+
+# 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 = []
+
+# If true, keep warnings as "system message" paragraphs in the built documents.
+#keep_warnings = False
+
+# If true, `todo` and `todoList` produce output, else they produce nothing.
+todo_include_todos = False
+
+
+# -- 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 = 'nature'
+
+# Theme options are theme-specific and customize the look and feel of a theme
+# further.  For a list of options available for each theme, see the
+# documentation.
+#html_theme_options = {}
+
+# Add any paths that contain custom themes here, relative to this directory.
+#html_theme_path = []
+
+# The name for this set of Sphinx documents.  If None, it defaults to
+# "<project> v<release> documentation".
+#html_title = None
+
+# A shorter title for the navigation bar.  Default is the same as html_title.
+#html_short_title = None
+
+# The name of an image file (relative to this directory) to place at the top
+# of the sidebar.
+html_logo = "img/tomoscan.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 = None
+
+# 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']
+
+# Add any extra paths that contain custom files (such as robots.txt or
+# .htaccess) here, relative to this directory. These files are copied
+# directly to the root of the documentation.
+#html_extra_path = []
+
+# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# using the given strftime format.
+#html_last_updated_fmt = '%b %d, %Y'
+
+# If true, SmartyPants will be used to convert quotes and dashes to
+# typographically correct entities.
+#html_use_smartypants = True
+
+# Custom sidebar templates, maps document names to template names.
+#html_sidebars = {}
+
+# Additional templates that should be rendered to pages, maps page names to
+# template names.
+#html_additional_pages = {}
+
+# If false, no module index is generated.
+#html_domain_indices = True
+
+# If false, no index is generated.
+#html_use_index = True
+
+# If true, the index is split into individual pages for each letter.
+#html_split_index = False
+
+# If true, links to the reST sources are added to the pages.
+#html_show_sourcelink = True
+
+# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
+#html_show_sphinx = True
+
+# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
+#html_show_copyright = True
+
+# If true, an OpenSearch description file will be output, and all pages will
+# contain a <link> tag referring to it.  The value of this option must be the
+# base URL from which the finished HTML is served.
+#html_use_opensearch = ''
+
+# This is the file name suffix for HTML files (e.g. ".xhtml").
+#html_file_suffix = None
+
+# Language to be used for generating the HTML full-text search index.
+# Sphinx supports the following languages:
+#   'da', 'de', 'en', 'es', 'fi', 'fr', 'h', 'it', 'ja'
+#   'nl', 'no', 'pt', 'ro', 'r', 'sv', 'tr'
+#html_search_language = 'en'
+
+# A dictionary with options for the search language support, empty by default.
+# Now only 'ja' uses this config value
+#html_search_options = {'type': 'default'}
+
+# The name of a javascript file (relative to the configuration directory) that
+# implements a search results scorer. If empty, the default will be used.
+#html_search_scorer = 'scorer.js'
+
+# Output file base name for HTML help builder.
+htmlhelp_basename = 'tomoscan'
+
+# -- 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': '',
+
+# Latex figure (float) alignment
+#'figure_align': 'htbp',
+}
+
+# Grouping the document tree into LaTeX files. List of tuples
+# (source start file, target name, title,
+#  author, documentclass [howto, manual, or own class]).
+# latex_documents = [
+#   (master_doc, 'Orange3ESRFAdd-on.tex', 'Orange3 ESRF Add-on Documentation',
+#    'Biolab', '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 = [
+    (master_doc, 'tomoscan', 'tomoscan documentation',
+     [author], 1)
+]
+
+htmlhelp_pages = [
+    (master_doc, 'tomoscan', 'tomoscan documentation',
+     [author], 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 = [
+  (master_doc, 'tomoscan', 'tomoscan Documentation',
+   author, 'tomoscan', 'utils for getting core information from scan',
+   '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'
+
+# If true, do not generate a @detailmenu in the "Top" node's menu.
+#texinfo_no_detailmenu = False
+
+nbsphinx_timeout = 60

doc/esrf.rst

+esrf package
+============
+
+Submodules
+----------
+
+esrf.edfscan module
+-------------------
+
+.. automodule:: tomoscan.esrf.edfscan
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+esrf.hdf5scan module
+--------------------
+
+.. automodule:: tomoscan.esrf.hdf5scan
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+esrf.mock module
+----------------
+
+.. automodule:: tomoscan.esrf.mock
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+esrf.utils module
+-----------------
+
+.. automodule:: tomoscan.esrf.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+Module contents
+---------------
+
+.. automodule:: tomoscan.esrf
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/img/tomoscan.svg

+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="48"
+   height="48"
+   viewBox="0 0 12.7 12.7"
+   version="1.1"
+   id="svg8"
+   inkscape:version="0.92.4 (5da689c313, 2019-01-14)"
+   sodipodi:docname="tomoscan.svg"
+   inkscape:export-filename="/users/payno/dev/esrf/tomography/tomoscan/doc/img/tomoscan.png"
+   inkscape:export-xdpi="2"
+   inkscape:export-ydpi="2">
+  <defs
+     id="defs2" />
+  <sodipodi:namedview
+     id="base"
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1.0"
+     inkscape:pageopacity="0.0"
+     inkscape:pageshadow="2"
+     inkscape:zoom="1.979899"
+     inkscape:cx="97.155975"
+     inkscape:cy="33.062436"
+     inkscape:document-units="mm"
+     inkscape:current-layer="text817"
+     showgrid="false"
+     units="px"
+     inkscape:window-width="1920"
+     inkscape:window-height="1103"
+     inkscape:window-x="0"
+     inkscape:window-y="27"
+     inkscape:window-maximized="1" />
+  <metadata
+     id="metadata5">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+        <dc:title />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <g
+     inkscape:label="Layer 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(0,-284.3)">
+    <g
+       aria-label="tomo
+scan"
+       transform="matrix(0.00918416,-0.96008695,1.0414913,0.00846631,0,0)"
+       style="font-style:normal;font-weight:normal;font-size:10.00487518px;line-height:0.5;font-family:sans-serif;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;stroke-width:0.25012189"
+       id="text817">
+      <path
+         d="m -308.37736,4.0723918 v 0.7767457 h 0.92574 v 0.3492913 h -0.92574 v 1.4850986 q 0,0.3346358 0.0904,0.429897 0.0928,0.095261 0.37372,0.095261 h 0.46165 v 0.3761598 h -0.46165 q -0.52027,0 -0.71812,-0.1929651 -0.19785,-0.1954077 -0.19785,-0.708353 V 5.1984288 h -0.32975 V 4.8491375 h 0.32975 V 4.0723918 Z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path823" />
+      <path
+         d="m -305.79798,5.1642324 q -0.3615,0 -0.57157,0.2833412 -0.21006,0.2808986 -0.21006,0.7718605 0,0.4909619 0.20762,0.7743031 0.21006,0.2808986 0.57401,0.2808986 0.35906,0 0.56913,-0.2833412 0.21006,-0.2833412 0.21006,-0.7718605 0,-0.4860767 -0.21006,-0.7694179 -0.21007,-0.2857838 -0.56913,-0.2857838 z m 0,-0.381045 q 0.58622,0 0.92086,0.381045 0.33464,0.3810451 0.33464,1.0552017 0,0.671714 -0.33464,1.0552017 -0.33464,0.381045 -0.92086,0.381045 -0.58867,0 -0.9233,-0.381045 -0.33219,-0.3834877 -0.33219,-1.0552017 0,-0.6741566 0.33219,-1.0552017 0.33463,-0.381045 0.9233,-0.381045 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path825" />
+      <path
+         d="m -301.66999,5.3742957 q 0.16854,-0.3028819 0.40303,-0.4469951 0.23449,-0.1441132 0.55202,-0.1441132 0.42746,0 0.6595,0.3004393 0.23205,0.2979968 0.23205,0.8500236 v 1.6511952 h -0.45188 V 5.9483059 q 0,-0.393258 -0.13923,-0.5837806 -0.13922,-0.1905225 -0.42501,-0.1905225 -0.34929,0 -0.55203,0.2320467 -0.20273,0.2320466 -0.20273,0.6326325 v 1.5461635 h -0.45188 V 5.9483059 q 0,-0.3957006 -0.13923,-0.5837806 -0.13923,-0.1905225 -0.4299,-0.1905225 -0.3444,0 -0.54714,0.2344893 -0.20273,0.2320466 -0.20273,0.6301899 v 1.5461635 h -0.45188 v -2.735708 h 0.45188 v 0.4250118 q 0.15388,-0.2515875 0.36883,-0.3712747 0.21495,-0.1196872 0.5105,-0.1196872 0.298,0 0.50562,0.151441 0.21006,0.1514409 0.31021,0.4396673 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path827" />
+      <path
+         d="m -297.86443,5.1642324 q -0.3615,0 -0.57156,0.2833412 -0.21007,0.2808986 -0.21007,0.7718605 0,0.4909619 0.20762,0.7743031 0.21007,0.2808986 0.57401,0.2808986 0.35907,0 0.56913,-0.2833412 0.21006,-0.2833412 0.21006,-0.7718605 0,-0.4860767 -0.21006,-0.7694179 -0.21006,-0.2857838 -0.56913,-0.2857838 z m 0,-0.381045 q 0.58623,0 0.92086,0.381045 0.33464,0.3810451 0.33464,1.0552017 0,0.671714 -0.33464,1.0552017 -0.33463,0.381045 -0.92086,0.381045 -0.58866,0 -0.9233,-0.381045 -0.33219,-0.3834877 -0.33219,-1.0552017 0,-0.6741566 0.33219,-1.0552017 0.33464,-0.381045 0.9233,-0.381045 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path829" />
+      <path
+         d="m -307.0779,9.9810327 v 0.4250113 q -0.19052,-0.0977 -0.3957,-0.146555 -0.20518,-0.04885 -0.42501,-0.04885 -0.33464,0 -0.50318,0.102589 -0.16609,0.102589 -0.16609,0.307767 0,0.156326 0.11968,0.246702 0.11969,0.08793 0.48119,0.168539 l 0.15389,0.0342 q 0.47875,0.102589 0.67904,0.290669 0.20274,0.185637 0.20274,0.520273 0,0.381045 -0.30289,0.603321 -0.30044,0.222276 -0.82804,0.222276 -0.21983,0 -0.4592,-0.04397 -0.23694,-0.04153 -0.50074,-0.127015 v -0.464094 q 0.24915,0.129458 0.49097,0.195408 0.24181,0.06351 0.47874,0.06351 0.31754,0 0.48852,-0.107475 0.17099,-0.109917 0.17099,-0.307767 0,-0.183195 -0.12458,-0.280898 -0.12213,-0.0977 -0.53981,-0.18808 l -0.15633,-0.03664 q -0.41768,-0.08793 -0.60332,-0.268686 -0.18564,-0.183195 -0.18564,-0.500732 0,-0.385931 0.27357,-0.595994 0.27358,-0.2100631 0.77675,-0.2100631 0.24915,0 0.46898,0.036639 0.21983,0.036639 0.40547,0.1099169 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path831" />
+      <path
+         d="m -304.24449,10.005459 v 0.420126 q -0.19052,-0.105031 -0.38349,-0.156326 -0.19052,-0.05374 -0.38593,-0.05374 -0.43722,0 -0.67904,0.278456 -0.24181,0.276013 -0.24181,0.776746 0,0.500732 0.24181,0.779188 0.24182,0.276013 0.67904,0.276013 0.19541,0 0.38593,-0.05129 0.19297,-0.05374 0.38349,-0.158769 v 0.415241 q -0.18808,0.08793 -0.39081,0.131901 -0.2003,0.04397 -0.42746,0.04397 -0.61797,0 -0.98192,-0.388372 -0.36395,-0.388373 -0.36395,-1.047874 0,-0.669272 0.36639,-1.052759 0.36883,-0.3834881 1.00879,-0.3834881 0.20762,0 0.40547,0.043967 0.19785,0.041524 0.38349,0.1270154 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path833" />
+      <path
+         d="m -302.21469,11.260953 q -0.5447,0 -0.75476,0.124573 -0.21007,0.124572 -0.21007,0.425011 0,0.239375 0.15633,0.381046 0.15877,0.139228 0.4299,0.139228 0.37371,0 0.59843,-0.263801 0.22717,-0.266243 0.22717,-0.70591 v -0.100147 z m 0.89643,-0.185637 v 1.560819 h -0.44943 v -0.415241 q -0.15389,0.249145 -0.38349,0.368832 -0.22961,0.117244 -0.5618,0.117244 -0.42013,0 -0.66927,-0.234489 -0.2467,-0.236932 -0.2467,-0.632632 0,-0.461651 0.30776,-0.69614 0.31021,-0.23449 0.92331,-0.23449 h 0.63019 v -0.04397 q 0,-0.31021 -0.20518,-0.478749 -0.20274,-0.170982 -0.57157,-0.170982 -0.23449,0 -0.45677,0.05618 -0.22227,0.05618 -0.42745,0.168539 v -0.415242 q 0.2467,-0.095261 0.47875,-0.1416702 0.23205,-0.048852 0.45188,-0.048852 0.59355,0 0.88666,0.3077671 0.29311,0.307767 0.29311,0.933072 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path835" />
+      <path
+         d="m -298.11601,10.98494 v 1.651195 h -0.44944 v -1.63654 q 0,-0.388372 -0.15144,-0.581338 -0.15144,-0.192965 -0.45433,-0.192965 -0.36394,0 -0.57401,0.232047 -0.21006,0.232047 -0.21006,0.632632 v 1.546164 h -0.45188 V 9.900427 h 0.45188 v 0.425012 q 0.16121,-0.246702 0.3786,-0.3688323 0.21984,-0.1221298 0.50562,-0.1221298 0.47142,0 0.71324,0.2931111 0.24182,0.290669 0.24182,0.857352 z"
+         style="font-size:5.00243759px;line-height:0.5;stroke-width:0.25012189"
+         id="path837" />
+    </g>
+  </g>
+</svg>

doc/index.rst

+tomoscan
+========
+
+.. toctree::
+   :maxdepth: 4
+
+   esrf
+   scanbase
+   scanfactory
+   unitsystem

doc/scanbase.rst

+scanbase module
+===============
+
+.. automodule:: tomoscan.scanbase
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/scanfactory.rst

+scanfactory module
+==================
+
+.. automodule:: tomoscan.scanfactory
+   :members:
+   :undoc-members:
+   :show-inheritance:

doc/unitsystem.rst

+unitsystem package
+==================
+
+Submodules
+----------
+
+unitsystem.metricsystem module
+------------------------------
+
+.. automodule:: tomoscan.unitsystem.metricsystem
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+
+
+Module contents
+---------------
+
+.. automodule:: tomoscan.unitsystem
+   :members:
+   :undoc-members:
+   :show-inheritance:

tomoscan/unitsystem/metricsystem.py

@@ -26,6 +26,9 @@ __authors__ = ["H. Payno"]
 __license__ = "MIT"
 __date__ = "01/09/2016"
 
+
+from typing import Union
+
 meter = 1.0
 m = meter
 
@@ -46,8 +49,10 @@ cm2 = centimeter * centimeter
 m2 = meter * meter
 
 
-def getUnitName(value):
-    """Return the name in (None, nm, cm, m, mm) from the given unit"""
+def getUnitName(value: Union[float, int]) -> str:
+    """
+    :return: name in (None, nm, cm, m, mm) from the given unit
+    """
     if value == nanometer:
         return 'nm'
     if value == millimeter: