diff --git a/.github/workflows/doc_deploy.yml b/.github/workflows/doc_deploy.yml new file mode 100644 index 00000000..f20e932c --- /dev/null +++ b/.github/workflows/doc_deploy.yml @@ -0,0 +1,31 @@ +name: page_deploy + +on: push + # Trigger the workflow on push or pull request, + # but only for the main branch + # push: + # branches: + # - main + +jobs: + deploy-book: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v2 + + # Install dependencies + - name: Set up Python + uses: actions/setup-python@v1 + with: + python-version: "3.8" + + # Build the book + - name: Build the book + run: | + make docs + # Push the book's HTML to github-pages + - name: GitHub Pages action + uses: peaceiris/actions-gh-pages@v3.6.1 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 00000000..a16ab9ce --- /dev/null +++ b/Makefile @@ -0,0 +1,10 @@ +.PHONY: docs + +docs: + rm -rf docs/_build/html + find docs/api ! -name 'index.rst' -type f -exec rm -f {} + + pip install -qr docs/requirements.txt + pip install -r requirements.txt + pip install -r requirements_dev.txt + pip install -e . + jb build docs \ No newline at end of file diff --git a/README.md b/README.md index 68408fa9..7bb28821 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,8 @@ # Sashimi - + + + ![tests](https://github.com/portugueslab/sashimi/workflows/tests/badge.svg?branch=master) [![Docs](https://img.shields.io/badge/docs-dev-brightgreen)](https://portugueslab.github.io/sashimi/) diff --git a/docs/Makefile b/docs/Makefile deleted file mode 100644 index d0c3cbf1..00000000 --- a/docs/Makefile +++ /dev/null @@ -1,20 +0,0 @@ -# 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 = source -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) diff --git a/docs/_config.yml b/docs/_config.yml new file mode 100644 index 00000000..131331e5 --- /dev/null +++ b/docs/_config.yml @@ -0,0 +1,58 @@ +# Book settings +# Learn more at https://jupyterbook.org/customize/config.html + +title: Sashimi +author: Diego Asua, Vilim Stih, Luigi Petrucco @portugueslab +logo: "../sashimi/icons/main_icon.png" +copyright: Portugues lab +release: 0.2.0 +# only_build_toc_files: true + +# Force re-execution of notebooks on each build. +# See https://jupyterbook.org/content/execute.html +execute: + execute_notebooks: force + +# Information about where the book exists on the web +repository: + url: https://github.com/portugueslab/sashimi # Online location of your book + path_to_book: docs # Optional path to your book, relative to the repository root + +# Add GitHub buttons to your book +# See https://jupyterbook.org/customize/config.html#add-a-link-to-your-repository +html: + use_issues_button: true + use_repository_button: true + use_edit_page_button : false # Whether to add an "edit this page" button to pages. If `true`, repository information in repository: must be filled in + extra_navbar : Powered by Jupyter Book # Will be displayed underneath the left navbar. + extra_footer : "Mantained by Federico Puppo" # Will be displayed underneath the footer. + +latex: + latex_engine : pdflatex # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex' + + +sphinx: + extra_extensions: + - sphinx.ext.viewcode + - sphinx.ext.napoleon + - sphinx.ext.autodoc + - sphinx_autodoc_typehints + - sphinx.ext.autosummary + - sphinx.ext.intersphinx + - sphinx.ext.coverage + - sphinx.ext.inheritance_diagram + - sphinx.ext.githubpages + + config: + autosummary_generate: True + autosummary_imported_members: True + html_theme: furo + templates_path: + - '_templates' + intersphinx_mapping: + python: + - "https://docs.python.org/3" + - null + numpy: + - "https://docs.scipy.org/doc/numpy/" + - null \ No newline at end of file diff --git a/docs/_templates/autosummary/class.rst b/docs/_templates/autosummary/class.rst new file mode 100644 index 00000000..38b014d1 --- /dev/null +++ b/docs/_templates/autosummary/class.rst @@ -0,0 +1,35 @@ +{{ fullname | escape | underline}} + +.. currentmodule:: {{ module }} + +.. autoclass:: {{ objname }} + :members: + :show-inheritance: + :inherited-members: + + {% block methods %} + + {% if methods %} + .. rubric:: {{ _('Methods') }} + + .. autosummary:: + :inherited-members: + {% for item in methods %} + {% if not item.startswith('_') %} + ~{{ name }}.{{ item }} + {% endif %} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block attributes %} + {% if attributes %} + .. rubric:: {{ _('Attributes') }} + + .. autosummary:: + :inherited-members: + {% for item in attributes %} + ~{{ name }}.{{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_templates/autosummary/module.rst b/docs/_templates/autosummary/module.rst new file mode 100644 index 00000000..86723344 --- /dev/null +++ b/docs/_templates/autosummary/module.rst @@ -0,0 +1,49 @@ +{{ fullname | escape | underline}} + +.. automodule:: {{ fullname }} + + {% block attributes %} + {% if attributes %} + .. rubric:: Module Attributes + + {% for item in attributes %} + .. autoattribute:: {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block classes %} + {% if classes %} + .. rubric:: {{ _('Classes') }} + + .. autosummary:: + :nosignatures: + :toctree: + {% for item in classes %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block functions %} + {% if functions %} + .. rubric:: {{ _('Functions') }} + + {% for item in functions %} + .. autofunction:: {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} + + {% block exceptions %} + {% if exceptions %} + .. rubric:: {{ _('Exceptions') }} + + .. autosummary:: + :nosignatures: + :toctree: + {% for item in exceptions %} + {{ item }} + {%- endfor %} + {% endif %} + {% endblock %} diff --git a/docs/_toc.yml b/docs/_toc.yml new file mode 100644 index 00000000..d26d500b --- /dev/null +++ b/docs/_toc.yml @@ -0,0 +1,22 @@ +- file: index + +- part: Overview + chapters: + - file: timeline + +- part: Configuration + chapters: + - file: configuration/installation + - file: configuration/configuration + +- part: Development + chapters: + - file: development/code_organization + +- part: Hardware + chapters: + - file: hardware/hardware + +- part: Api + chapters: + - file: api/index \ No newline at end of file diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 00000000..622ae81b --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,24 @@ +.. _api: + +API Reference +============= + +Information on specific functions, classes, and methods. + + +Modules +------- + +For the average user's workflows. + +.. autosummary:: + :toctree: + :recursive: + + + sashimi.events + sashimi.hardware.cameras + sashimi.utilities + sashimi.processes.logging + sashimi.config + sashimi.hardware.scanning \ No newline at end of file diff --git a/docs/configuration/configuration.md b/docs/configuration/configuration.md new file mode 100644 index 00000000..233a9125 --- /dev/null +++ b/docs/configuration/configuration.md @@ -0,0 +1,36 @@ +# Configuring Sashimi + +Sashimi includes the `sashimi-config` module that lets you interact with the hardware and software +settings from command line. You can display the current configuration of the system.: + + sashimi-config show + +You can ask sashimi for help: + + sashimi --help + +More information on its usage can be found by asking `sashimi-config` for help: + + sashimi-config --help + +You can add and modify parameters just from the command line. For example, to set the piezo waveform readout channel to `Dev1/ao0:0` just run: + + sashimi-config edit -n z_board.write.channel -v Dev1/ao0:0 + +Or to modify the minimum and maximum voltage (in Volts) of the channel: + + sashimi-config edit -n piezo.position_write.min_val -v 0 + sashimi-config edit -n piezo.position_write.max_val -v 10 + + +## Starting the software from command line + +Open a new anaconda prompt and activate your environment like above. Then run: + + sashimi + +Add the option `--scopeless`: + + sashimi --scopeless + +If you want to run the software with mock hardware, such as for debugging or developing. diff --git a/docs/configuration/installation.md b/docs/configuration/installation.md new file mode 100644 index 00000000..f6739a55 --- /dev/null +++ b/docs/configuration/installation.md @@ -0,0 +1,32 @@ +# Installation + +[Install the latest Anaconda](https://www.anaconda.com/) distribution of Python 3. + +Clone this repository and navigate to the main folder `../sashimi` + +## Recommended: Create a new environment + +It is a good practice to create an environment for every project. The provided `environment.yml` sets up almost all required dependencies (see below). + + conda env create -f {path to environment.yml} + +You can activate the environment by running: + + conda activate sashimi + +After this you moght have to install two extra dependencies for controlling a Cobolt laser: + + pip install pyvisa + pip install pyvisa-py + +## Install with pip + +For a non-editable installation run: + + pip install . + +Otherwise, if you want to contribute to the project as a developer, for editable installation run: + + pip install -e . + +Now you are ready to go! diff --git a/docs/source/development/code_organization.md b/docs/development/code_organization.md similarity index 100% rename from docs/source/development/code_organization.md rename to docs/development/code_organization.md diff --git a/docs/source/hardware.md b/docs/hardware/hardware.md similarity index 100% rename from docs/source/hardware.md rename to docs/hardware/hardware.md diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..7b7e34fd --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +# Welcome to the Sashimi documentation! + + + + +![tests](https://github.com/portugueslab/sashimi/workflows/tests/badge.svg?branch=master) +[![Docs](https://img.shields.io/badge/docs-dev-brightgreen)](https://portugueslab.github.io/sashimi/) +[![Coverage Status](https://coveralls.io/repos/github/portugueslab/sashimi/badge.svg)](https://coveralls.io/github/portugueslab/sashimi) +[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black) +[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.4122062.svg)](https://doi.org/10.5281/zenodo.4122062) +[![Python 3.8](https://img.shields.io/badge/python-3.8-blue.svg)](https://www.python.org/) + +Sashimi is a user-friendly software for efficient control of digital scanned light sheet microscopes (DSLMs). +It is developed by members of the [PortuguesLab](http://www.portugueslab.com/) + at the Technical University of Munich and Max Planck Institute of Neurobiology. Sashimi relies on the fast, multidimensional + [Napari viewer](https://github.com/napari/napari). + +While built for a particular microscope configuration, the modular architecture allows for easy replacement of +hardware by other vendors (we will help with and welcome contributions for supporting other cameras, boards and light sources). + +## Table of Contents + +```{tableofcontents} +``` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat deleted file mode 100644 index 9534b018..00000000 --- a/docs/make.bat +++ /dev/null @@ -1,35 +0,0 @@ -@ECHO OFF - -pushd %~dp0 - -REM Command file for Sphinx documentation - -if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build -) -set SOURCEDIR=source -set BUILDDIR=build - -if "%1" == "" goto help - -%SPHINXBUILD% >NUL 2>NUL -if errorlevel 9009 ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -goto end - -:help -%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% - -:end -popd diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 00000000..33d44626 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +jupyter-book +jupytext +sphinx_autodoc_typehints +furo +recommonmark diff --git a/docs/source/conf.py b/docs/source/conf.py deleted file mode 100644 index 4c47010b..00000000 --- a/docs/source/conf.py +++ /dev/null @@ -1,58 +0,0 @@ -# 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 - -# -- 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. -# -import os -import sys - -sys.path.insert(0, os.path.abspath(".")) -sys.path.insert(0, os.path.abspath("../")) - - -# -- Project information ----------------------------------------------------- - -project = "Sashimi" -copyright = "Portugues lab" -author = "Diego Asua, Vilim Stih, Luigi Petrucco @portugueslab" - -# The full version, including alpha/beta/rc tags -release = "0.2.0" - - -# -- General configuration --------------------------------------------------- - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ["myst_parser", "sphinx.ext.napoleon", "sphinx.ext.githubpages"] - -# 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 = [] - - -# -- 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 = "alabaster" - -# 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"] - -napoleon_google_docstring = False diff --git a/docs/source/configuration.md b/docs/source/configuration.md deleted file mode 100644 index c5e844fb..00000000 --- a/docs/source/configuration.md +++ /dev/null @@ -1 +0,0 @@ -# Configuring Sashimi \ No newline at end of file diff --git a/docs/source/index.md b/docs/source/index.md deleted file mode 100644 index cd4b52fd..00000000 --- a/docs/source/index.md +++ /dev/null @@ -1,19 +0,0 @@ -# Welcome to the Sashimi documentation! - -An index here: - -```{toctree} -intro -configuration -development -hardware -:maxdepth: 3 -:caption: Contents: -``` - -API documentation: - -```{eval-rst} -:ref:`modindex` -``` - diff --git a/docs/source/intro.md b/docs/source/intro.md deleted file mode 100644 index cfc66e24..00000000 --- a/docs/source/intro.md +++ /dev/null @@ -1,8 +0,0 @@ -```{admonition} Here's my title -:class: warning - -Here's my admonition content -``` - -```{include} ../../README.md -``` \ No newline at end of file diff --git a/docs/source/timeline.md b/docs/source/timeline.md deleted file mode 100644 index e69de29b..00000000 diff --git a/docs/timeline.md b/docs/timeline.md new file mode 100644 index 00000000..0ad65f93 --- /dev/null +++ b/docs/timeline.md @@ -0,0 +1 @@ +# Timeline diff --git a/requirements_dev.txt b/requirements_dev.txt index 478f247a..8db54878 100644 --- a/requirements_dev.txt +++ b/requirements_dev.txt @@ -6,4 +6,4 @@ coverage pre-commit black flake8 -isort \ No newline at end of file +isort