From 5853033760e7f522cd0cc649ce9ae79a80ba7b40 Mon Sep 17 00:00:00 2001 From: SeanLeRoy Date: Mon, 4 Dec 2023 10:48:49 -0800 Subject: [PATCH] Simplify docs --- .github/workflows/docs.yml | 32 ------- .gitignore | 5 - CONTRIBUTING.md | 2 - Justfile | 26 +----- README.md | 39 +++++--- docs/conf.py | 186 ------------------------------------- docs/contributing.rst | 1 - docs/index.rst | 14 --- docs/installation.rst | 51 ---------- pyproject.toml | 12 --- 10 files changed, 29 insertions(+), 339 deletions(-) delete mode 100644 .github/workflows/docs.yml delete mode 100644 docs/conf.py delete mode 100644 docs/contributing.rst delete mode 100644 docs/index.rst delete mode 100644 docs/installation.rst diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml deleted file mode 100644 index 0045385..0000000 --- a/.github/workflows/docs.yml +++ /dev/null @@ -1,32 +0,0 @@ -name: Documentation - -on: - push: - branches: - - main - -jobs: - docs: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v4 - - name: Set up Python - uses: actions/setup-python@v4 - with: - python-version: "3.10" - - uses: extractions/setup-just@v1 - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - - name: Install Dependencies - run: | - python -m pip install --upgrade pip - pip install .[docs] - - name: Generate Docs - run: | - just generate-docs - touch docs/_build/.nojekyll - - name: Publish Docs - uses: JamesIves/github-pages-deploy-action@v4 - with: - folder: docs/_build/ diff --git a/.gitignore b/.gitignore index 2557254..45a0c1b 100644 --- a/.gitignore +++ b/.gitignore @@ -68,11 +68,6 @@ instance/ # Scrapy stuff: .scrapy -# Sphinx documentation -docs/_build/ -docs/bioio_lif.*rst -docs/modules.rst - # PyBuilder target/ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bdcf25d..76f51c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,11 +66,9 @@ Available recipes: build # run lint and then run tests clean # clean all build, python, and lint files default # list all available commands - generate-docs # generate Sphinx HTML documentation install # install with all deps lint # lint, format, and check all files release # release a new version - serve-docs # generate Sphinx HTML documentation and serve to browser tag-for-release version # tag a new version test # run tests update-from-cookiecutter # update this repo using latest cookiecutter-bioio-reader diff --git a/Justfile b/Justfile index bf77975..dff17d9 100644 --- a/Justfile +++ b/Justfile @@ -5,7 +5,6 @@ default: # clean all build, python, and lint files clean: rm -fr build - rm -fr docs/_build rm -fr dist rm -fr .eggs find . -name '*.egg-info' -exec rm -fr {} + @@ -22,7 +21,7 @@ clean: # install with all deps install: - pip install -e .[lint,test,docs] + pip install -e .[lint,test] # install dependencies, setup pre-commit, download test resources setup-dev: @@ -43,29 +42,6 @@ build: just lint just test -# generate Sphinx HTML documentation -generate-docs: - rm -f docs/bioio_lif*.rst - rm -f docs/modules.rst - sphinx-apidoc -o docs bioio_lif **/tests - python -msphinx "docs" "docs/_build" - - -# Generate project URI for browser opening -# We replace here to handle windows paths -# Windows paths are normally `\` separated but even in the browser they use `/` -# https://stackoverflow.com/a/61991869 -project_uri := if "os_family()" == "unix" { - justfile_directory() -} else { - replace(justfile_directory(), "\\", "/") -} - -# generate Sphinx HTML documentation and serve to browser -serve-docs: - just generate-docs - python -mwebbrowser -t "file://{{project_uri}}/docs/_build/index.html" - # tag a new version tag-for-release version: git tag -a "{{version}}" -m "{{version}}" diff --git a/README.md b/README.md index d98510f..66752e3 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,50 @@ # bioio-lif [![Build Status](https://github.com/bioio-devs/bioio-lif/actions/workflows/ci.yml/badge.svg)](https://github.com/bioio-devs/bioio-lif/actions) -[![Documentation](https://github.com/bioio-devs/bioio-lif/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio-lif) +[![PyPI version](https://badge.fury.io/py/bioio-lif.svg)](https://badge.fury.io/py/bioio-lif) +[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0) +[![Python 3.9+](https://img.shields.io/badge/python-3.9,3.10,3.11-blue.svg)](https://www.python.org/downloads/release/python-390/) -A BioIO reader plugin for reading LIF (Leica Image File) images. +A BioIO reader plugin for reading LIF (Leica) images using `readlif` -This plugin is intended to be used in conjunction with [bioio](https://github.com/bioio-devs/bioio) --- + +## Documentation + +[See the full documentation on our GitHub pages site](https://bioio-devs.github.io/bioio/OVERVIEW.html) - the generic use and installation instructions there will work for this package. + +Information about the base reader this package relies on can be found in the `bioio-base` repository [here](https://github.com/bioio-devs/bioio-base) + ## Installation **Stable Release:** `pip install bioio-lif`
**Development Head:** `pip install git+https://github.com/bioio-devs/bioio-lif.git` -## Quickstart +## Example Usage (see full documentation for more examples) +Install bioio-lif alongside bioio: + +`pip install bioio bioio-lif` + + +This example shows a simple use case for just accessing the pixel data of the image +by explicitly passing this `Reader` into the `BioImage`. Passing the `Reader` into +the `BioImage` instance is optional as `bioio` will automatically detect installed +plug-ins and auto-select the most recently installed plug-in that supports the file +passed in. ```python -from bioio_lif import Reader +from bioio import BioImage +import bioio_lif -r = Reader("my-image.ext") -r.dims +img = BioImage("my_file.lif", reader=bioio_lif.Reader) +img.data ``` -## Documentation +## Issues +[_Click here to view all open issues in bioio-devs organization at once_](https://github.com/search?q=user%3Abioio-devs+is%3Aissue+is%3Aopen&type=issues&ref=advsearch) or check this repository's issue tab. -For full package documentation please visit [bioio-devs.github.io/bioio-lif](https://bioio-devs.github.io/bioio-lif). ## Development See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code. - -**MIT License** diff --git a/docs/conf.py b/docs/conf.py deleted file mode 100644 index 3d53cb9..0000000 --- a/docs/conf.py +++ /dev/null @@ -1,186 +0,0 @@ -#!/usr/bin/env python -# -*- coding: utf-8 -*- -# -# bioio-lif documentation build configuration file, created by -# sphinx-quickstart on Fri Jun 9 13:47:02 2017. -# -# 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. - -# 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 - -import bioio_lif - -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 lib ext - "sphinx.ext.autodoc", - "sphinx.ext.autosummary", - "sphinx.ext.intersphinx", - "sphinx.ext.viewcode", - # Installed Sphinx ext - "sphinx_copybutton", - # Doc installs - "m2r2", - "numpydoc", -] - -copybutton_prompt_text = r">>> |\.\.\. |\$ |In \[\d*\]: | {2,5}\.\.\.: | {5,8}: " -copybutton_prompt_is_regexp = True - -numpydoc_show_class_members = False - -sphinx_tabs_disable_tab_closing = True - -# Control autodoc -autoclass_content = "both" # include init doc with class - -# 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": "restructuredtext", - ".txt": "markdown", - ".md": "markdown", -} - -# The main toctree document. -main_doc = "index" - -# General information about the project. -project = "bioio-lif" -copyright = "2023" -author = "bioio-devs" - -# 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 = bioio_lif.__version__ -# The full version, including alpha/beta/rc tags. -release = bioio_lif.__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 - - -# -- 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 = "furo" - -# 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 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"] - - -# -- Options for HTMLHelp output --------------------------------------- - -# Output file base name for HTML help builder. -htmlhelp_basename = "bioio_lifdoc" - - -# -- 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 = [ - ( - main_doc, - "bioio_lif.tex", - "bioio-lif Documentation", - "bioio-devs", - "manual", - ), -] - - -# -- Options for manual page output ------------------------------------ - -# One entry per manual page. List of tuples -# (source start file, name, description, authors, manual section). -man_pages = [(main_doc, "bioio_lif", "bioio-lif 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 = [ - ( - main_doc, - "bioio_lif", - "bioio-lif Documentation", - author, - "bioio_lif", - "A BioIO reader plugin for reading LIF (Leica Image File) images.", - ), -] diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 4fc5016..0000000 --- a/docs/contributing.rst +++ /dev/null @@ -1 +0,0 @@ -.. mdinclude:: ../CONTRIBUTING.md diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index 9356d53..0000000 --- a/docs/index.rst +++ /dev/null @@ -1,14 +0,0 @@ -Welcome to bioio-lif's documentation! -====================================== - -.. toctree:: - :hidden: - :maxdepth: 1 - :caption: Contents: - - Overview - installation - Package modules - contributing - -.. mdinclude:: ../README.md diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index 57195d1..0000000 --- a/docs/installation.rst +++ /dev/null @@ -1,51 +0,0 @@ -.. highlight:: shell - -============ -Installation -============ - - -Stable release --------------- - -To install bioio-lif, run this command in your terminal: - -.. code-block:: console - - $ pip install bioio-lif - -This is the preferred method to install bioio-lif, as it will always install the most recent stable release. - -If you don't have `pip`_ installed, this `Python installation guide`_ can guide -you through the process. - -.. _pip: https://pip.pypa.io -.. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/ - - -From sources ------------- - -The sources for bioio-lif can be downloaded from the `Github repo`_. - -You can either clone the public repository: - -.. code-block:: console - - $ git clone git://github.com/bioio-devs/bioio-lif - -Or download the `tarball`_: - -.. code-block:: console - - $ curl -OL https://github.com/bioio-devs/bioio-lif/tarball/main - -Once you have a copy of the source, you can install it with: - -.. code-block:: console - - $ python setup.py install - - -.. _Github repo: https://github.com/bioio-devs/bioio-lif -.. _tarball: https://github.com/bioio-devs/bioio-lif/tarball/main diff --git a/pyproject.toml b/pyproject.toml index 7c68043..33c6b99 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -56,17 +56,6 @@ test = [ "quilt3", # no pin to avoid pip cycling (boto is really hard to manage) "types-PyYAML>=6.0.12.9", ] -docs = [ - # Sphinx + Doc Gen + Styling - "m2r2>=0.2.7", - "Sphinx>=4.0.0", - "furo>=2022.4.7", - # Extensions - "numpydoc", - "sphinx-copybutton", - # TODO: Pins - "docutils>=0.18,<0.19", -] # entry points # https://peps.python.org/pep-0621/#entry-points @@ -108,7 +97,6 @@ ignore = [ "Justfile", ".cookiecutter.yaml", "scripts/*", - "*docs/*", ] [tool.mypy]