merge master -Dorg -Ssuccess-only: PR 187 (Rtd)

.bumpversion.cfg

@@ -18,3 +18,4 @@ values =
 [bumpversion:part:build]
 
 [bumpversion:file:setup.py]
+[bumpversion:file:docs/conf.py]

.github/workflows/sphinx.yml

@@ -0,0 +1,34 @@
+# Builds the Sphinx documentation in the specified folder.
+# Default values are docs/ for the directory where the Sphinx
+# documentation is located and true to run linkcheck
+# To pass a new folder, set directory_path to the folder path
+# Pass the arguments you wish to run, default command is make clean html linkcheck
+
+---
+name: sphinx
+
+on: 
+  push:
+  pull_request:
+  schedule:
+    - cron: '0 0 * * 0'
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    env: 
+      directory_path:
+      sphinx_commands: clean html linkcheck # commands to run. Update accordingly
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-python@v2
+      - name: Sphinx install
+        run: pip install --upgrade sphinx
+      - name: Set directory
+        run:  |
+          VAR=${{ env.directory_path }}
+          echo "docs_dir="${VAR:-./docs} >> $GITHUB_ENV
+      - name: Build doc
+        run: |
+          cd $docs_dir
+          make ${{ env.sphinx_commands }}

.gitignore

@@ -3,3 +3,4 @@
 *.pyc
 .gitignore
 *.DS_Store*
+docs/_build

.readthedocs.yml

@@ -0,0 +1,9 @@
+# Required
+version: 2
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+python:
+   version: 3.7

README.rst

@@ -1,6 +1,9 @@
 .. image:: https://github.com/ome/omero-scripts/workflows/OMERO/badge.svg
     :target: https://github.com/ome/omero-scripts/actions
 
+.. image:: https://github.com/ome/omero-scripts/workflows/sphinx/badge.svg
+    :target: https://github.com/ome/omero-scripts/actions
+
 .. image:: https://badge.fury.io/py/omero-scripts.svg
     :target: https://badge.fury.io/py/omero-scripts
 
@@ -12,34 +15,37 @@ OMERO.scripts API. All scripts (e.g. ``*.py``) present in the
 directory will be automatically distributed with all binary
 builds. Which file-endings will be detected and how they
 will be launched are both configured centrally in the server.
-``.py``, ``.jy", and ``.m`` (MATLAB) files should all be detected
+``.py``, ``.jy``, and ``.m`` (MATLAB) files should all be detected
 by default starting with OMERO 5.
 
 
 Categories
-----------
+==========
 
 Scripts are separated into several categories, one per directory.
 
-| In the directory       | should be scripts which ...                                                   |
-| ----------------       | ---------------------                                                         |
++------------------------+-------------------------------------------------------------------------------+
+| Directory              | Description                                                                   |
++========================+===============================================================================+                                                    
 | **analysis_scripts**   | crunch images to produce numerical results and similar tasks                  |
++------------------------+-------------------------------------------------------------------------------+
 | **export_scripts**     | take one or more images as an input, and produce a representation for exchange|
++------------------------+-------------------------------------------------------------------------------+
 | **figure_scripts**     | take one or more images as an input, and produce a summary representation     |
-| **hcs_scripts**        | work with screens/plates/wells rather than just images                        |
++------------------------+-------------------------------------------------------------------------------+
 | **import_scripts**     | are run on images after import for extra processing                           |
-| **processing_scripts** | create new images from existing images or other data                          |
-| **setup_scripts**      | are executed once, often by administrators, to configure OMERO itself         |
++------------------------+-------------------------------------------------------------------------------+
 | **util_scripts**       | perform other miscellaneous tasks like cleaning up or optimizing OMERO itself |
++------------------------+-------------------------------------------------------------------------------+
 
 
 Scripts which would like to rely on other scripts can
-use:
+use::
 
     import omero.<sub_dir>.<script_name>
 
 For this to work, the official script in question must
-be properly importable, i.e.:
+be properly importable, i.e.::
 
     def run():
         client = omero.scripts.client(...)
@@ -49,28 +55,54 @@ be properly importable, i.e.:
 
 
 OMERO User Scripts
-------------------
+==================
 
 If you would like to provide your own scripts for others to install
-into their OMERO installations, please see http://openmicroscopy.org/info/scripts
+into their OMERO installations, please see https://openmicroscopy.org/info/scripts
 
 
 Testing
--------
+=======
 
 Integration tests under ``test/`` require an OMERO server with scripts installed.
 The tests are run by Travis for open PRs using omero-test-infra to deploy OMERO
 via Docker containers.
 
-To run tests locally:
+To run tests locally::
 
 	# All tests
 	$ python setup.py test
 
 	# Single test in a single file
 	$ python setup.py test -t test/integration/test_util_scripts.py -k test_dataset_to_plate
 
+Usage
+=====
+
+See https://omero-scripts.readthedocs.io/en/stable/
+
+Release process
+===============
+
+This repository uses `bump2version <https://pypi.org/project/bump2version/>`_ to manage version numbers.
+To tag a release run::
+
+    $ bumpversion release
+
+This will remove the ``.dev0`` suffix from the current version, commit, and tag the release.
+
+To switch back to a development version run::
+
+    $ bumpversion --no-tag [major|minor|patch]
+
+specifying ``major``, ``minor`` or ``patch`` depending on whether the development branch will be a `major, minor or patch release <https://semver.org/>`_. This will also add the ``.dev0`` suffix.
+
+Remember to ``git push`` all commits and tags.s essential.
+
+The CI pipeline will automatically deploy the tag onto PyPI.
+
+
 Copyright
----------
+=========
 
-2010-2020, The Open Microscopy Environment
+2010-2021, The Open Microscopy Environment

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+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/analysis_scripts.rst

@@ -0,0 +1,22 @@
+Analysis scripts
+================
+
+Kymograph
+---------
+
+.. automodule:: Kymograph
+   :members:
+
+
+Kymograph Analysis
+------------------
+
+.. automodule:: Kymograph_Analysis
+   :members:
+
+
+Plot Profile
+------------
+
+.. automodule:: Plot_Profile
+   :members:

docs/conf.py

@@ -0,0 +1,178 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+from datetime import datetime
+import os
+import sys
+from sphinx.util import logging
+logger = logging.getLogger(__name__)
+
+
+# -- Path setup --------------------------------------------------------------
+
+# 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.
+#
+def get_scripts(directory):
+    """
+    Find all the scripts available
+    """
+    scripts = []
+
+    # Walk the tree.
+    for root, directories, files in os.walk(directory):
+        for filename in files:
+            if filename.endswith(".py") and "_init_" not in filename:
+                scripts.append(filename.replace('\n', '').replace(".py", ""))
+
+    return scripts
+
+
+def find_scripts_entry(file_name):
+    """
+    Find the entries corresponding to the scripts.
+    """
+
+    with open(file_name) as file:
+        lines = file.readlines()
+
+    entries = []
+    for line in lines:
+        if "automodule" in line:
+            values = line.split(".. automodule::")
+            entries.append(values[1].replace('\n', '').strip())
+    return entries
+
+
+def compare(list1, list2):
+    """
+    Return the elements not common to both lists
+    """
+    return [i for i in list1 + list2 if i not in list1 or i not in list2]
+
+
+# List of directories to scan and add the path.
+directories = ['../omero/analysis_scripts', '../omero/export_scripts',
+               '../omero/figure_scripts', '../omero/import_scripts',
+               '../omero/util_scripts']
+
+scripts = []
+entries = []
+for d in directories:
+    sys.path.insert(0, d)
+    scripts.extend(get_scripts(d))
+    p = d.split("/")
+    name = "%s.rst" % (p[len(p) - 1])
+    entries.extend(find_scripts_entry(name))
+
+# Indicate the scripts not listed for documentation
+if len(entries) < len(scripts):
+    common = compare(scripts, entries)
+    logger.warning("automodule entries missing for:\n" + '\n'.join(common))
+
+# -- Project information -----------------------------------------------------
+
+# The master toctree document.
+master_doc = 'index'
+
+project = u'omero scripts'
+now = datetime.now()
+author = u'Open Microscopy Environment'
+copyright = u'2016-%d, %s ' % (now.year, author)
+
+# The full version, including alpha/beta/rc tags
+# The short X.Y version.
+version = '5.6.2.dev0'
+release = version
+
+
+# -- General configuration ---------------------------------------------------
+
+extlinks = {}
+
+# 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.extlinks',
+    "sphinx_rtd_theme",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
+
+# Build docs without external dependencies
+autodoc_mock_imports = ['numpy', 'omero-py', 'omero', "PIL"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = 'sphinx'
+
+# -- 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'
+
+# 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 = []
+
+# 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, 'OMEROScripts.tex', u'OMERO Scripts Documentation',
+     author, 'manual'),
+]
+
+
+# -- 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, 'omeroscripts', u'OMERO Scripts Documentation',
+     [author], 1)
+]
+
+
+# -- 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, 'OMEROScripts', u'OMERO Script Documentation',
+     author, 'OMEROScripts', 'One line description of project.',
+     'Miscellaneous'),
+]
+
+
+# -- Options for Epub output -------------------------------------------------
+
+# Bibliographic Dublin Core info.
+epub_title = project
+
+# The unique identifier of the text. This can be a ISBN number
+# or the project homepage.
+#
+# epub_identifier = ''
+
+# A unique identification for the text.
+#
+# epub_uid = ''
+
+# A list of files that should not be packed into the epub file.
+epub_exclude_files = ['search.html']