diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml new file mode 100644 index 0000000..d7906c7 --- /dev/null +++ b/.github/workflows/publish-docs.yml @@ -0,0 +1,44 @@ +name: "Publish documentation" +on: + push: + branches: + - master + + workflow_dispatch: # Manual trigger + +jobs: + build: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v4 + + - uses: actions/setup-python@v5 + with: + python-version: '3.10' + cache: 'pip' + + - name: Create environment + run: | + pip install --upgrade pip + python -m venv .venv + source .venv/bin/activate + + - name: Install dependencies + run: pip install -r requirements.txt + + - name: Install package + run: pip install -e . + + - name: Build docs + run: | + cd docs + make clean + make html + + - name: Deploy docs + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/_build/html + diff --git a/.gitignore b/.gitignore index cb3e38e..fc41eb8 100644 --- a/.gitignore +++ b/.gitignore @@ -62,6 +62,7 @@ instance/ # Sphinx documentation docs/_build/ +docs/api/ # PyBuilder target/ @@ -81,6 +82,7 @@ celerybeat-schedule # virtualenv venv/ ENV/ +.venv/ # Spyder project settings .spyderproject @@ -88,6 +90,5 @@ ENV/ # Rope project settings .ropeproject -doc/_build/ -doc/py-api/ - +# MacOS +.DS_Store diff --git a/README.md b/README.md index 4734db5..d5ff668 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,7 @@ repository is located at http://github.com/Caltech-IPAC/firefly. Standalone Firefly servers may be obtained from [this Dockerhub repository](https://hub.docker.com/r/ipac/firefly/). -For detailed explanation on the usage, see [the online documentation](https://firefly-client.lsst.io), -or [the documentation source file](doc/index.rst). Following is a very simple example: +For detailed explanation on the usage, see [the online documentation](https://caltech-ipac.github.io/firefly_client). Following is a very simple example: ``` from firefly_client import FireflyClient diff --git a/doc/Makefile b/doc/Makefile deleted file mode 100644 index 3fde329..0000000 --- a/doc/Makefile +++ /dev/null @@ -1,64 +0,0 @@ -# Makefile for Sphinx documentation -# - -# You can set these variables from the command line. -SPHINXOPTS = -SPHINXBUILD = sphinx-build -PAPER = -BUILDDIR = _build - -# Internal variables. -PAPEROPT_a4 = -D latex_paper_size=a4 -PAPEROPT_letter = -D latex_paper_size=letter -ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . -# the i18n builder cannot share the environment and doctrees with the others -I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) . - -.PHONY: help -help: - @echo "Please use \`make ' where is one of" - @echo " html to make standalone HTML files" - @echo " linkcheck to check all external links for integrity" - @echo " doctest to run all doctests embedded in the documentation (if enabled)" - @echo " coverage to run coverage check of the documentation (if enabled)" - @echo " dummy to check syntax errors of document sources" - -.PHONY: clean -clean: - rm -rf $(BUILDDIR)/* - rm -rf py-api - -.PHONY: html -html: - $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html - @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." - -ltd: html - ltd-mason-travis --html-dir $(BUILDDIR)/html - - -.PHONY: linkcheck -linkcheck: - $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck - @echo - @echo "Link check complete; look for any errors in the above output " \ - "or in $(BUILDDIR)/linkcheck/output.txt." - -.PHONY: doctest -doctest: - $(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest - @echo "Testing of doctests in the sources finished, look at the " \ - "results in $(BUILDDIR)/doctest/output.txt." - -.PHONY: coverage -coverage: - $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage - @echo "Testing of coverage in the sources finished, look at the " \ - "results in $(BUILDDIR)/coverage/python.txt." - -.PHONY: dummy -dummy: - $(SPHINXBUILD) -b dummy $(ALLSPHINXOPTS) $(BUILDDIR)/dummy - @echo - @echo "Build finished. Dummy builder generates no files." diff --git a/doc/_static/Readme.md b/doc/_static/Readme.md deleted file mode 100644 index e69de29..0000000 diff --git a/doc/conf.py b/doc/conf.py deleted file mode 100644 index 4b1e192..0000000 --- a/doc/conf.py +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env python -"""Sphinx configurations to build package documentation.""" - -from documenteer.sphinxconfig.stackconf import build_package_configs - -import firefly_client - -_g = globals() -_g.update(build_package_configs( - project_name='firefly_client', - copyright='2016-2019 California Institute of Technology', - version=firefly_client.__version__, - doxygen_xml_dirname=None)) - -# intersphinx_mapping['astropy'] = ('http://docs.astropy.org/en/stable', None) - -# DEBUG only -automodsumm_writereprocessed = False diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/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) diff --git a/docs/_static/custom-icon.js b/docs/_static/custom-icon.js new file mode 100644 index 0000000..f21e31b --- /dev/null +++ b/docs/_static/custom-icon.js @@ -0,0 +1,18 @@ +/******************************************************************************* + * Set a custom icon for pypi as it's not available in the fa built-in brands + * + * Taken from: https://github.com/pydata/pydata-sphinx-theme/blob/69f827d8d7259315f77363cf928e57c908789b72/docs/_static/custom-icon.js + */ +FontAwesome.library.add( + (faListOldStyle = { + prefix: "fa-custom", + iconName: "pypi", + icon: [ + 17.313, // viewBox width + 19.807, // viewBox height + [], // ligature + "e001", // unicode codepoint - private use area + "m10.383 0.2-3.239 1.1769 3.1883 1.1614 3.239-1.1798zm-3.4152 1.2411-3.2362 1.1769 3.1855 1.1614 3.2369-1.1769zm6.7177 0.00281-3.2947 1.2009v3.8254l3.2947-1.1988zm-3.4145 1.2439-3.2926 1.1981v3.8254l0.17548-0.064132 3.1171-1.1347zm-6.6564 0.018325v3.8247l3.244 1.1805v-3.8254zm10.191 0.20931v2.3137l3.1777-1.1558zm3.2947 1.2425-3.2947 1.1988v3.8254l3.2947-1.1988zm-8.7058 0.45739c0.00929-1.931e-4 0.018327-2.977e-4 0.027485 0 0.25633 0.00851 0.4263 0.20713 0.42638 0.49826 1.953e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36226 0.13215-0.65608-0.073306-0.65613-0.4588-6.28e-5 -0.38556 0.2938-0.80504 0.65613-0.93662 0.068422-0.024919 0.13655-0.038114 0.20156-0.039466zm5.2913 0.78369-3.2947 1.1988v3.8247l3.2947-1.1981zm-10.132 1.239-3.2362 1.1769 3.1883 1.1614 3.2362-1.1769zm6.7177 0.00213-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2439-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.016195v3.8275l3.244 1.1805v-3.8254zm16.9 0.21143-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm-3.4124 1.2432-3.2947 1.1988v3.8254l3.2947-1.1988zm-6.6585 0.019027v3.8247l3.244 1.1805v-3.8254zm13.485 1.4497-3.2947 1.1988v3.8247l3.2947-1.1981zm-3.4145 1.2411-3.2926 1.2016v3.8247l3.2926-1.2009zm2.4018 0.38127c0.0093-1.83e-4 0.01833-3.16e-4 0.02749 0 0.25633 0.0085 0.4263 0.20713 0.42638 0.49826 1.97e-4 0.38532-0.29327 0.80469-0.65542 0.93662-0.36188 0.1316-0.65525-0.07375-0.65542-0.4588-1.95e-4 -0.38532 0.29328-0.80469 0.65542-0.93662 0.06842-0.02494 0.13655-0.03819 0.20156-0.03947zm-5.8142 0.86403-3.244 1.1805v1.4201l3.244 1.1805z", // svg path (https://simpleicons.org/icons/pypi.svg) + ], + }) + ); \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..b84657f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,54 @@ +# Configuration file for the Sphinx documentation builder. +# +# For the full list of built-in configuration values, see the documentation: +# https://www.sphinx-doc.org/en/master/usage/configuration.html + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'firefly_client' +copyright = '2024, Caltech/IPAC Firefly Developers' +author = 'Caltech/IPAC Firefly Developers' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'sphinx_automodapi.automodapi', + 'myst_parser' +] + +templates_path = ['_templates'] +exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] + + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'pydata_sphinx_theme' +html_static_path = ['_static'] +html_js_files = ["custom-icon.js"] + +html_last_updated_fmt = '' + +# See https://pydata-sphinx-theme.readthedocs.io/en/stable/user_guide/layout.html +html_theme_options = { + "icon_links": [ + { + "name": "GitHub", + "url": "https://github.com/Caltech-IPAC/firefly_client", + "icon": "fa-brands fa-github", + }, + { + "name": "PyPI", + "url": "https://pypi.org/project/firefly-client", + "icon": "fa-custom fa-pypi", + }, + ], + "footer_start": ["copyright", "last-updated"], + "footer_end": ["sphinx-version", "theme-version"], +} + + +# -- Options for extensions ------------------------------------------------- +myst_heading_anchors = 3 diff --git a/docs/development/guide.rst b/docs/development/guide.rst new file mode 100644 index 0000000..825dce7 --- /dev/null +++ b/docs/development/guide.rst @@ -0,0 +1,31 @@ +################# +Local development +################# + +Get latest source from ``master`` branch at https://github.com/Caltech-IPAC/firefly_client. + + +Environment Setup +----------------- + +TBD + + +Building documentation +---------------------- + +Make sure you have the virtual/conda environment activated and documentation +dependencies installed in that environment. + +Then do: + +.. code-block:: shell + + cd docs + make clean && make html + +Open ``docs/_build/html/index.html`` in your browser to see the documentation +website. + +Each time you make a change in documentation source, build it using +above command and reload the above file in browser. \ No newline at end of file diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 0000000..dce4f54 --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,11 @@ +############### +Developer Guide +############### + + +.. toctree:: + :maxdepth: 2 + + guide + new-release-procedure.md + diff --git a/doc/new-release-procedure.md b/docs/development/new-release-procedure.md similarity index 93% rename from doc/new-release-procedure.md rename to docs/development/new-release-procedure.md index 312c1c5..cd60d50 100644 --- a/doc/new-release-procedure.md +++ b/docs/development/new-release-procedure.md @@ -1,6 +1,6 @@ -## How to create a firefly_client release +# Making a release -### Procedure +## Procedure 1. To push a new release you must be a maintainer in pypi ([see pypi below](#pypi)) 2. Bump version in setup.py (this step is might be done in the PR) 3. Clean out old distribution @@ -34,13 +34,13 @@ 11. Make is release with github, using the tag above - https://github.com/Caltech-IPAC/firefly_client/releases -### PYPI +## PYPI - https://pypi.org/project/firefly-client/ - Currently two maintainers - Testing site: https://test.pypi.org/project/firefly-client/ -### Optional Test installation +## Optional Test installation 1. To create a test release you must be a mainainer on testpypi 2. Create the distribution (see above) @@ -48,7 +48,7 @@ 4. `pip uninstall firefly_client` 5. `pip install --verbose --index-url https://testpypi.python.org/pypi firefly_client` -### Conda and conda-forge +## Conda and conda-forge Anytime the version tag is updated conda-forge it set up to do a pull and add `firefly_client` to its distribution. diff --git a/doc/index.rst b/docs/index.rst similarity index 72% rename from doc/index.rst rename to docs/index.rst index 0150cda..8c85d0e 100644 --- a/doc/index.rst +++ b/docs/index.rst @@ -3,7 +3,7 @@ .. _firefly_client: ##################################################### -firefly\_client - Python API to Firefly visualization +firefly_client - Python API to Firefly visualization ##################################################### `firefly_client` provides a Python API to the Firefly visualization framework. @@ -30,38 +30,33 @@ to upload and display astronomical images, tables and catalogs. .. _firefly_client-using: - Using firefly_client ==================== .. toctree:: - :maxdepth: 1 + :maxdepth: 2 - getting-started - initializing-vanilla - initializing-jupyterlab - displaying-images - overlaying-regions - viewing-tables - charting - slate-layout - plot-interface - callbacks-extensions - firefly-server + Usage -.. _firefly_client-contributing +.. _firefly_client-contributing: -Contributing -============ +Developer Guide +=============== + +.. toctree:: + :maxdepth: 2 + + Development -``firefly_client`` is developed at https://github.com/Caltech-IPAC/firefly_client. .. _firefly_client-pyapi: Python API reference ==================== -.. automodapi:: firefly_client - :no-inheritance-diagram: +.. toctree:: + :maxdepth: 3 + + API diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..954237b --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=. +set BUILDDIR=_build + +%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.https://www.sphinx-doc.org/ + exit /b 1 +) + +if "%1" == "" goto help + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/reference.rst b/docs/reference.rst new file mode 100644 index 0000000..60ea4c1 --- /dev/null +++ b/docs/reference.rst @@ -0,0 +1,8 @@ +############# +API reference +############# + +.. automodapi:: firefly_client + :no-inheritance-diagram: + :no-heading: + diff --git a/doc/callbacks-extensions.rst b/docs/usage/callbacks-extensions.rst similarity index 100% rename from doc/callbacks-extensions.rst rename to docs/usage/callbacks-extensions.rst diff --git a/doc/charting.rst b/docs/usage/charting.rst similarity index 100% rename from doc/charting.rst rename to docs/usage/charting.rst diff --git a/doc/displaying-images.rst b/docs/usage/displaying-images.rst similarity index 99% rename from doc/displaying-images.rst rename to docs/usage/displaying-images.rst index 608a386..9e39798 100644 --- a/doc/displaying-images.rst +++ b/docs/usage/displaying-images.rst @@ -1,5 +1,6 @@ +################# Displaying Images ------------------ +################# Since Firefly was originally developed to visualize data products from astronomical archives, displaying an image is a two-step process of @@ -156,8 +157,8 @@ To search the survey: Displaying HiPS Images ---------------------- - +TBD Displaying 3-color Images ------------------------- - +TBD diff --git a/doc/getting-started.rst b/docs/usage/getting-started.rst similarity index 97% rename from doc/getting-started.rst rename to docs/usage/getting-started.rst index b88390a..b54e17e 100644 --- a/doc/getting-started.rst +++ b/docs/usage/getting-started.rst @@ -1,3 +1,7 @@ +############### +Getting Started +############### + Prerequisites ============= diff --git a/docs/usage/index.rst b/docs/usage/index.rst new file mode 100644 index 0000000..6f0683e --- /dev/null +++ b/docs/usage/index.rst @@ -0,0 +1,26 @@ +#################### +Using firefly_client +#################### + +.. toctree:: + :maxdepth: 2 + + getting-started + initializing-vanilla + displaying-images + overlaying-regions + viewing-tables + charting + callbacks-extensions + + +Examples +-------- + +You can find a list of notebooks/scripts that demonstrate the use of +firefly_client in |nbviewer_examples|. + +.. |nbviewer_examples| raw:: html + + this directory (rendered in nbviewer) \ No newline at end of file diff --git a/doc/initializing-vanilla.rst b/docs/usage/initializing-vanilla.rst similarity index 97% rename from doc/initializing-vanilla.rst rename to docs/usage/initializing-vanilla.rst index 3a07e38..d93acf6 100644 --- a/doc/initializing-vanilla.rst +++ b/docs/usage/initializing-vanilla.rst @@ -1,5 +1,6 @@ +##################################### Initializing a FireflyClient instance -------------------------------------- +##################################### Once a Firefly server has been identified, the connection parameters can be used to initialize a :class:`FireflyClient` instance. By default, the value diff --git a/doc/overlaying-regions.rst b/docs/usage/overlaying-regions.rst similarity index 100% rename from doc/overlaying-regions.rst rename to docs/usage/overlaying-regions.rst diff --git a/doc/viewing-tables.rst b/docs/usage/viewing-tables.rst similarity index 100% rename from doc/viewing-tables.rst rename to docs/usage/viewing-tables.rst diff --git a/requirements.txt b/requirements.txt index 7b5683f..5572af8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,9 @@ -# Documentation dependencies -documenteer[pipelines]>=0.5.0,<0.6.0 - -requests~=2.22.0 +requests~=2.30.0 setuptools~=41.0.1 -websocket-client~=0.58.0 \ No newline at end of file +websocket-client~=0.58.0 + +# Documentation dependencies +Sphinx~=7.1.0 +sphinx-automodapi +pydata-sphinx-theme +myst-parser \ No newline at end of file