Merge pull request #126 from portugueslab/doc_automated

Added automated way to build documentation and deploy it to github pages

.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/[email protected]
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: ./docs/_build/html

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

README.md

@@ -1,10 +1,8 @@
 # Sashimi
 
-<a href="url"><img 
-src="https://github.com/portugueslab/sashimi/blob/master/sashimi/icons/main_icon.png" 
-align="left" 
-height="190" 
-width="270"></a>
+<img src="https://raw.githubusercontent.com/portugueslab/sashimi/master/sashimi/icons/main_icon.png" align="left" height="190" width="270">
+
+
 
 ![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/)

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 <a href="https://jupyterbook.org">Jupyter Book</a>  # 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

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 %}

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 %}

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

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

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.

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!

docs/index.md

@@ -0,0 +1,24 @@
+# Welcome to the Sashimi documentation!
+
+<img src="https://raw.githubusercontent.com/portugueslab/sashimi/master/sashimi/icons/main_icon.png" align="left" height="190" width="270">
+
+
+![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}
+```