Merge pull request #1 from DiamondLightSource/docs

dkazanc · web-flow · commit 4f08320b64a4 · 2024-09-04T11:20:32.000+01:00
Adding documentation
diff --git a/.github/workflows/httomo_backends_docs.yml b/.github/workflows/httomo_backends_docs.yml
@@ -0,0 +1,59 @@
+name: HTTomo-backends docs
+
+on:
+  workflow_dispatch:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - main
+
+jobs:
+  build-docs-publish:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -el {0}
+    steps:
+        - name: Checkout repository code
+          uses: actions/checkout@v4
+
+        - name: Setup Python 3.10
+          uses: actions/setup-python@v4
+          with:
+            python-version: '3.10'
+
+        - name: httomo-backends-docs
+          uses: conda-incubator/setup-miniconda@v2
+          with:
+            auto-update-conda: false
+            activate-environment: httomo-backends-docs
+            environment-file: ./docs/source/doc-conda-requirements.yml
+
+        - name: Build api docs
+          run: sphinx-apidoc -feT -t=./docs/source/_templates -o ./docs/source/api ./httomo_backends
+
+        - name: Generate yaml templates
+          run: |            
+            pip install httomolib 
+            pip install httomolibgpu --no-deps
+
+        - name: Generate yaml templates
+          run: |
+            python ./httomo_backends/scripts/yaml_templates_generator.py -i ./httomo_backends/methods_database/backends/tomopy/tomopy_modules.yaml -o ./docs/build/yaml_templates/tomopy
+            python ./httomo_backends/scripts/yaml_unsupported_tomopy_remove.py -t ./docs/build/yaml_templates/tomopy -l ./httomo_backends/methods_database/backends/tomopy/tomopy.yaml
+            python ./httomo_backends/scripts/yaml_templates_generator.py -i ./httomo_backends/methods_database/backends/httomolib/httomolib_modules.yaml -o ./docs/build/yaml_templates/httomolib
+            python ./httomo_backends/scripts/yaml_templates_generator.py -i ./httomo_backends/methods_database/backends/httomolibgpu/httomolibgpu_modules.yaml -o ./docs/build/yaml_templates/httomolibgpu
+
+        - name: Generate yml docs
+          run: python ./docs/source/yaml_doc_generator.py
+
+        - name: Build html
+          run: sphinx-build -a -E -b html ./docs/source/ ./docs/build/
+
+        - name: Publish docs
+          if: github.ref_type == 'tag' || github.ref_name == 'main'
+          run: ghp-import -n -p -f ./docs/build
+          env:
+            GITHUB_TOKEN: ${{ github.token }}
diff --git a/.github/workflows/httomo_backends_pypi_publish.yml b/.github/workflows/httomo_backends_pypi_publish.yml
@@ -25,8 +25,8 @@ jobs:
           $CONDA/bin/conda install conda-forge::pyyaml
           $CONDA/bin/pip install setuptools wheel
           $CONDA/bin/pip install build          
-          $CONDA/bin/pip install httomolib==2.1
-          $CONDA/bin/pip install --no-deps httomolibgpu==2.1.1
+          $CONDA/bin/pip install httomolib
+          $CONDA/bin/pip install --no-deps httomolibgpu
           $CONDA/bin/conda list
       - name: Generate yaml templates
         run: |
diff --git a/README.rst b/README.rst
@@ -6,16 +6,15 @@ Purpose of HTTomo-backends
 
 **HTTomo-backends** is a package to support `HTTomo <https://diamondlightsource.github.io/httomo/>`_ software and it contains the following elements:
 
-* YAML templates for backends methods
-* Scripts that automatically generate YAML templates
+* YAML templates for `backends <https://diamondlightsource.github.io/httomo/backends/list.html/>`_  methods.
+* Scripts that automatically generate YAML templates during documentation build
 * Supporting scripts to calculate memory, size and padding estimators of the methods
 
 
 Install HTTomo-backends
 =======================
-HTTomo backends is released to support a specific version of `HTTomo <https://diamondlightsource.github.io/httomo/>`_. Install it to provide the same version of HTTomo that is currently installed. 
 
 .. code-block:: console
 
-   $ pip install httomo-backends==*version_number*
+   $ pip install httomo-backends
 
diff --git a/docs/source/__init__.py b/docs/source/__init__.py
diff --git a/docs/source/_templates/module.rst_t b/docs/source/_templates/module.rst_t
@@ -0,0 +1,7 @@
+{%- if show_headings %}:mod:`{{ basename }}`
+============================================
+{%- endif %}
+.. automodule:: {{ qualname }}
+{%- for option in automodule_options %}
+   :{{ option }}:
+{%- endfor %}
diff --git a/docs/source/backends/templates.rst b/docs/source/backends/templates.rst
@@ -0,0 +1,41 @@
+.. _reference_templates:
+
+======================
+Methods YAML Templates
+======================
+
+This section contains YAML templates for `backends <https://diamondlightsource.github.io/httomo/backends/list.html/>`_. These are ready-to-use templates can be either copy-pasted or
+directy accessed by installing `httomo-backends` package.
+
+.. note:: When you click on a module you can find a link to the API of that module. This is where the description of the method and its arguments can be found.
+
+
+.. _reference_templates_tomopy:
+
+TomoPy Modules
+---------------
+
+.. toctree::
+   :glob:
+
+   ../api/tomopy*
+
+.. _reference_templates_httomolibgpu:
+
+HTTomolibgpu Modules
+--------------------
+
+.. toctree::
+   :glob:
+
+   ../api/httomolibgpu*
+
+.. _reference_templates_httomolib:
+
+HTTomolib Modules
+------------------
+
+.. toctree::
+   :glob:
+
+   ../api/httomolib.*
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+# ---------------------------------------------------------------------------
+# Copyright 2024 Diamond Light Source Ltd.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either ecpress or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+# ---------------------------------------------------------------------------
+# Created By  : Tomography Team at DLS <scientificsoftware@diamond.ac.uk>
+
+# -- General configuration ------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+import os
+import sys
+from datetime import date
+from unittest import mock
+
+# 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.
+
+sys.path.insert(0, os.path.abspath("../.."))
+
+# -- Mock imports -------------------------------------------------------------
+
+
+# Mock imports instead of full environment in readthedocs
+MOCK_MODULES = [
+    "click",
+    "yaml",
+]
+
+for mod_name in MOCK_MODULES:
+    sys.modules[mod_name] = mock.Mock()
+
+# ------------------------------------------------------------------------------
+
+project = "httomo-backends"
+copyright = f"{date.today().year}, Diamond Light Source"
+
+# Specify a base language to help assistive technology
+language = "en"
+
+# Save the commit hash, this is displayed in the page title
+release = os.popen('git log -1 --format="%H"').read().strip()
+
+# Set version as the latest tag in the current branch
+version = os.popen("git describe --tags --abbrev=0").read().strip()
+
+# Add any Sphinx extension module names here, as strings. They can be extensions
+# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
+extensions = [
+    # Generates api files
+    "sphinx.ext.autodoc",
+    # Generates a short summary from docstring
+    "sphinx.ext.autosummary",
+    # Allows parsing of google style docstrings
+    "sphinx.ext.napoleon",
+    # Add links to highlighted source code
+    "sphinx.ext.viewcode",
+    # Allows a grid layout and dropdown boxes
+    "sphinx_panels",
+    # copy to clipboard button
+    "sphinx_copybutton",
+    # use jupyter notebooks
+    "nbsphinx",
+    #'IPython.sphinxext.ipython_console_highlighting',
+    "sphinx.ext.githubpages",
+    # Generate .nojekyll file for git pages build
+]
+
+autosummary_generate = True
+numfig = True
+template_patterns = ["_templates"]
+
+# The name of the Pygments (syntax highlighting) style to use.
+pygments_style = "sphinx"
+
+# -- Options for HTML output --------------------------------------------------
+
+html_theme = "sphinx_book_theme"
+html_title = "httomo-backends documentation page"
+html_copy_source = True
+html_last_updated_fmt = ""
+html_use_smartypants = True
+
+html_theme_options = {
+    "show_toc_level": 1,
+    "navbar_align": "left",  # [left, content, right] For testing that the navbar items align properly
+}
+
+
+html_context = {
+    "github_user": "HTTomo",
+    "github_repo": "https://github.com/DiamondLightSource/httomo-backends",
+    "github_version": "main",
+    "doc_path": "docs",
+}
+
+
+def setup(app):
+    app.add_css_file("css/general.css")
diff --git a/docs/source/doc-conda-requirements.yml b/docs/source/doc-conda-requirements.yml
@@ -0,0 +1,20 @@
+name: httomo-backends-docs
+channels:
+  - conda-forge
+dependencies:
+  - python>=3.10
+  - numpy
+  - tomopy==1.15
+  - sphinx
+  - sphinx-book-theme
+  - nbsphinx
+  - pandoc
+  - jinja2
+  - sphinx-panels
+  - sphinx-copybutton
+  - pyyaml
+  - ipython
+  - ghp-import
+  - loguru
+  - graypy
+  - tqdm
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -0,0 +1,17 @@
+.. include:: ../../README.rst
+
+.. _backends_content:
+
+.. toctree::
+    :caption: YAML Templates
+    :maxdepth: 2
+
+    backends/templates
+
+.. _utilities_content:
+
+.. toctree::
+    :caption: Utilities
+    :maxdepth: 2
+
+    utilities/yaml_generator
diff --git a/docs/source/utilities/yaml_generator.rst b/docs/source/utilities/yaml_generator.rst
@@ -0,0 +1,33 @@
+.. _utilities_yamlgenerator:
+
+Templates generator
+*******************
+:ref:`backends_content` can be generated automatically using the YAML generator tool `provided <https://github.com/DiamondLightSource/httomo/tree/main/scripts/yaml_templates_generator.py>`_ in the Github repo.
+
+The script does the following:
+
+* Generates a list of YAML files for all accessible on import methods in a chosen software package, e.g., TomoPy.
+* Modifies and/or removes some extracted parameters in YAML templates to make the templates compatible with HTTomo.
+
+How does it work:
+
+* The user would need to provide a YAML file with the listed *modules* you would like to inspect and extract the methods from. For instance, for the TomoPy package this would be:
+
+.. code-block:: yaml
+
+    - tomopy.misc.corr
+    - tomopy.misc.morph
+
+* The generator can be applied using the following command:
+
+.. code-block:: console
+
+   $ python -m yaml_templates_generator -i /path/to/modules.yaml -o /path/to/outputfolder/
+
+Please note that the package from which the modules are extracted, must be installed into your conda environment.
+
+**For TomoPy templates only.** After templates have been generated for TomoPy, we need to remove the ones that are not currently supported by HTTomo. We do that by looking into the library file that exists in HTTomo for TomoPy.
+
+.. code-block:: console
+
+   $ python -m remove_unsupported_templates -t /path/to/templates/ -l /path/to/library/file
diff --git a/docs/source/yaml_doc_generator.py b/docs/source/yaml_doc_generator.py
diff --git a/docs/sphinx-build.sh b/docs/sphinx-build.sh
