Document the API (#216)

* MNT #215 get project parameters * DOC #215 existing API documentation * STY #215 isort * DOC #215 workflow * DOC #215 * DOC #215 * DOC #215 * DOC #215 * DOC #215 * DOC #215 use pydata-sphinx-theme * DOC #215 handle edge case for Sphinx * DOC #215 preliminary user-facing content * DOC #199 to be described * DOC add sphinx-design * DOC #215 * DOC #215
BCDA-APS · Apr 18, 2024 · 2342915 · 2342915
1 parent 897f940
commit 2342915
Show file tree

Hide file tree

Showing 34 changed files with 372 additions and 105 deletions.
diff --git a/.github/workflows/pages.yml → .github/workflows/docs.yml b/.github/workflows/pages.yml → .github/workflows/docs.yml
@@ -19,9 +19,13 @@ on:
         required: true
         default: false
 
+defaults:
+  run:
+    shell: bash -l {0}
+
 jobs:
 
-  pages:
+  docs:
     runs-on: ubuntu-latest
 
     steps:
@@ -51,8 +55,20 @@ jobs:
       run: pip install --no-deps -e . -vv
 
     - name: Sphinx
+      id: deployment
       run: make -C docs html
 
+    - name: Diagnostic
+      run: ls -lAFgh docs/build/html
+      # ${{ steps.deployment.outputs.artifact }}
+
+    - name: Upload Docs ZIP file as artifact
+      uses: actions/upload-artifact@v4
+      with:
+        name: gemviz-docs
+        path: docs/build/html
+        # ${{ steps.deployment.outputs.artifact }}
+
     - name: Publish (push gh-pages branch) only on demand
       uses: peaceiris/actions-gh-pages@v4
       if: ${{ github.event.inputs.deploy }}

diff --git a/README.md b/README.md
@@ -36,22 +36,14 @@ This project is still in development.
 We have [plans for production
 release](https://github.com/orgs/BCDA-APS/projects/6).
 Until the production release, you should run `gemviz`
-as would a developer by following these instructions:
+as would a developer by following the [installation](file:///home/prjemian/Documents/projects/BCDA-APS/gemviz/docs/build/html/install.html) instructions.
 
-1. Navigate to a directory where you have similar software projects
-2. `git clone https://github.com/BCDA-APS/gemviz`
-   - only need to do this once, assumes you have `git` command
-3. `cd gemviz`
-4. `conda env create --force -n gemviz -f ./env.yml`
-   - only need to do this once, assumes you have `conda` command
-5. `conda activate gemviz`
-6. `pip install -e .`
-7. `gemviz &`
-
-The [gemviz package is now available on PyPI](https://pypi.org/project/gemviz/) which means
-a development version can be installed via `pip`:
+The gemviz package is now available on [PyPI](https://pypi.org/project/gemviz/)
+and [conda-forge](https://anaconda.org/conda-forge/gemviz). A Development
+version for either can be installed with one of these commands:
 
 ```bash
+conda install conda-forge::gemviz
 pip install gemviz
 ```
 

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,7 +1,9 @@
 coverage
 coveralls
+pydata-sphinx-theme
 pytz
 setuptools-scm
 sphinx
+sphinx-design
 sphinx-tabs
 tzdata
diff --git a/docs/source/_static/gemviz_gui.png b/docs/source/_static/gemviz_gui.png
diff --git a/docs/source/api.rst b/docs/source/api.rst
@@ -0,0 +1,10 @@
+====================================
+Source Code Documentation
+====================================
+
+.. toctree::
+   :glob:
+   :caption: Contents:
+
+   api/*
+   testing
diff --git a/docs/source/api/aboutdialog.rst b/docs/source/api/aboutdialog.rst
@@ -0,0 +1,7 @@
+====================================
+About Dialog
+====================================
+
+.. automodule:: gemviz.aboutdialog
+    :members:
+    :private-members:
diff --git a/docs/source/api/app.rst b/docs/source/api/app.rst
@@ -0,0 +1,7 @@
+====================================
+Application starting point.
+====================================
+
+.. automodule:: gemviz.app
+    :members:
+    :private-members:
diff --git a/docs/source/api/bluesky_runs_catalog.rst b/docs/source/api/bluesky_runs_catalog.rst
@@ -0,0 +1,7 @@
+====================================
+BRC_MVC
+====================================
+
+.. automodule:: gemviz.bluesky_runs_catalog
+    :members:
+    :private-members:
diff --git a/docs/source/api/bluesky_runs_catalog_run_viz.rst b/docs/source/api/bluesky_runs_catalog_run_viz.rst
@@ -0,0 +1,7 @@
+====================================
+bluesky_runs_catalog_run_viz
+====================================
+
+.. automodule:: gemviz.bluesky_runs_catalog_run_viz
+    :members:
+    :private-members:
diff --git a/docs/source/api/bluesky_runs_catalog_search.rst b/docs/source/api/bluesky_runs_catalog_search.rst
@@ -0,0 +1,7 @@
+====================================
+bluesky_runs_catalog_search
+====================================
+
+.. automodule:: gemviz.bluesky_runs_catalog_search
+    :members:
+    :private-members:
diff --git a/docs/source/api/bluesky_runs_catalog_table_model.rst b/docs/source/api/bluesky_runs_catalog_table_model.rst
@@ -0,0 +1,7 @@
+====================================
+bluesky_runs_catalog_table_model
+====================================
+
+.. automodule:: gemviz.bluesky_runs_catalog_table_model
+    :members:
+    :private-members:
diff --git a/docs/source/api/bluesky_runs_catalog_table_view.rst b/docs/source/api/bluesky_runs_catalog_table_view.rst
@@ -0,0 +1,7 @@
+====================================
+bluesky_runs_catalog_table_view
+====================================
+
+.. automodule:: gemviz.bluesky_runs_catalog_table_view
+    :members:
+    :private-members:
diff --git a/docs/source/api/chartview.rst b/docs/source/api/chartview.rst
@@ -0,0 +1,7 @@
+====================================
+Chartview
+====================================
+
+.. automodule:: gemviz.chartview
+    :members:
+    :private-members:
diff --git a/docs/source/api/date_time_range_slider.rst b/docs/source/api/date_time_range_slider.rst
@@ -0,0 +1,7 @@
+====================================
+DateTimeRangeSlider
+====================================
+
+.. automodule:: gemviz.date_time_range_slider
+    :members:
+    :private-members:
diff --git a/docs/source/api/licensedialog.rst b/docs/source/api/licensedialog.rst
@@ -0,0 +1,7 @@
+====================================
+License Dialog
+====================================
+
+.. automodule:: gemviz.licensedialog
+    :members:
+    :private-members:
diff --git a/docs/source/api/mainwindow.rst b/docs/source/api/mainwindow.rst
@@ -0,0 +1,7 @@
+====================================
+Main Window of GUI
+====================================
+
+.. automodule:: gemviz.mainwindow
+    :members:
+    :private-members:
diff --git a/docs/source/api/range_slider.rst b/docs/source/api/range_slider.rst
@@ -0,0 +1,7 @@
+====================================
+Range Slider
+====================================
+
+.. automodule:: gemviz.range_slider
+    :members:
+    :private-members:
diff --git a/docs/source/api/select_fields_tablemodel.rst b/docs/source/api/select_fields_tablemodel.rst
@@ -0,0 +1,7 @@
+====================================
+select_fields_tablemodel
+====================================
+
+.. automodule:: gemviz.select_fields_tablemodel
+    :members:
+    :private-members:
diff --git a/docs/source/api/select_fields_tableview.rst b/docs/source/api/select_fields_tableview.rst
@@ -0,0 +1,7 @@
+====================================
+select_fields_tableview
+====================================
+
+.. automodule:: gemviz.select_fields_tableview
+    :members:
+    :private-members:
diff --git a/docs/source/api/select_stream_fields.rst b/docs/source/api/select_stream_fields.rst
@@ -0,0 +1,7 @@
+====================================
+select_stream_fields
+====================================
+
+.. automodule:: gemviz.select_stream_fields
+    :members:
+    :private-members:
diff --git a/docs/source/api/tapi.rst b/docs/source/api/tapi.rst
@@ -0,0 +1,7 @@
+============================================
+TAPI: Tiled Application Programmer Interface
+============================================
+
+.. automodule:: gemviz.tapi
+    :members:
+    :private-members:
diff --git a/docs/source/api/tiledserverdialog.rst b/docs/source/api/tiledserverdialog.rst
@@ -0,0 +1,7 @@
+====================================
+tiledserverdialog
+====================================
+
+.. automodule:: gemviz.tiledserverdialog
+    :members:
+    :private-members:
diff --git a/docs/source/api/user_settings.rst b/docs/source/api/user_settings.rst
@@ -0,0 +1,7 @@
+====================================
+User Settings
+====================================
+
+.. automodule:: gemviz.user_settings
+    :members:
+    :private-members:
diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst
@@ -0,0 +1,7 @@
+====================================
+Utility Functions
+====================================
+
+.. automodule:: gemviz.utils
+    :members:
+    :private-members:
diff --git a/docs/source/changes.rst b/docs/source/changes.rst
@@ -0,0 +1,9 @@
+.. _changes:
+
+..
+	CHANGES
+	=======
+
+	title provided in CHANGES.rst file
+
+.. include:: ../../CHANGES.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -3,18 +3,54 @@
 # For the full list of built-in configuration values, see the documentation:
 # https://www.sphinx-doc.org/en/master/usage/configuration.html
 
+# -- Path setup --------------------------------------------------------------
+
+import pathlib
+import sys
+import tomllib
+from importlib.metadata import version
+
+sys.path.insert(0, str(pathlib.Path().absolute().parent.parent))
+import gemviz  # noqa
+
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "gemviz"
-copyright = "2023, Fanny Rodolakis, Pete Jemian, Ollivier Gassant"
-author = "Fanny Rodolakis, Pete Jemian, Ollivier Gassant"
-release = "0"
+root_path = pathlib.Path(__file__).parent.parent.parent
+
+with open(root_path / "pyproject.toml", "rb") as fp:
+    toml = tomllib.load(fp)
+metadata = toml["project"]
+
+gh_org = "BCDA-APS"
+project = metadata["name"]
+copyright = toml["tool"]["copyright"]["copyright"]
+author = "Ollivier Gassant, Fanny Rodolakis, Pete Jemian"
+description = metadata["description"]
+rst_prolog = f".. |author| replace:: {author}"
+github_url = f"https://github.com/{gh_org}/{project}"
+
+# -- Special handling for version numbers ------------------------------------
+# https://github.com/pypa/setuptools_scm#usage-from-sphinx
+
+release = version(project)
+version = ".".join(release.split(".")[:2])
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-extensions = []
+extensions = """
+    sphinx.ext.autodoc
+    sphinx.ext.autosummary
+    sphinx.ext.coverage
+    sphinx.ext.githubpages
+    sphinx.ext.inheritance_diagram
+    sphinx.ext.mathjax
+    sphinx.ext.todo
+    sphinx.ext.viewcode
+    sphinx_design
+""".split()
+extensions.append("sphinx_tabs.tabs")  # this must be last
 
 templates_path = ["_templates"]
 exclude_patterns = []
@@ -23,5 +59,20 @@
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = "alabaster"
 html_static_path = ["_static"]
+html_theme = "pydata_sphinx_theme"
+html_title = f"{project} {version}"
+
+# https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#confval-autodoc_mock_imports
+autodoc_mock_imports = """
+    h5py
+    httpx
+    matplotlib
+    numpy
+    PyQt5
+    pyRestTable
+    spec2nexus
+    tiled
+    xarray
+    yaml
+""".split()