Merge pull request #35 from BCDA-APS/30-prettify-the-docs

Make home page of docs prettier

.github/workflows/code.yml

@@ -47,16 +47,24 @@ jobs:
           cache-environment-key: env-key-${{ matrix.python-version }}
           condarc: |
             channel-priority: flexible
-          environment-file: environment.yml
+          # environment-file: environment.yml
           environment-name: anaconda-test-env-py-${{ matrix.python-version }}
           create-args: >-
+            apsu::aps-dm-api
             caproto
             coveralls
+            pyepics
             pytest
             pytest-cov
             python=${{ matrix.python-version }}
             setuptools-scm
 
+      - name: Local pip install
+        shell: bash -l {0}
+        run: |
+          set -vxeuo pipefail
+          python -m pip install -e .[all]
+
       - name: Run tests with pytest & coverage
         shell: bash -l {0}
         run: |

.github/workflows/docs.yml

@@ -37,35 +37,36 @@ jobs:
       run: |
         echo "The docs will be published from this workflow run."
 
-    # - name: Install pandoc
-    #   run: |
-    #     sudo apt-get update && \
-    #     sudo apt-get -y install pandoc
-
-    - name: Set time zone
-      run: echo "TZ=America/Chicago" >> "$GITHUB_ENV"
+    - uses: actions/setup-python@v5
+      with:
+        python-version: "3.11"
 
-    # TODO: review requirements
-    - name: Sphinx build
-      id: deployment
-      uses: sphinx-notes/pages@v3
+    - name: Checkout
+      uses: actions/checkout@master
       with:
-        documentation_path: ./docs/source
-        publish: false
-        python_version: "3.11"
-        requirements_path: ./docs/requirements.txt
+        fetch-depth: 0 # otherwise, you will fail to push refs to dest repo
+
+    - name: update pip
+      run: |
+        pip install --upgrade pip
 
-    - name: Diagnostic
-      run: ls -lAFgh ${{ steps.deployment.outputs.artifact }}
+    - name: Install package
+      run: |
+        pip install -e .[doc]
+
+    - name: Sphinx
+      id: deployment
+      run: |
+        TZ=UTC make -C docs html
 
     - name: Upload Docs ZIP file as artifact
       uses: actions/upload-artifact@v4
       with:
         name: apsbss-docs
-        path: ${{ steps.deployment.outputs.artifact }}
+        path: docs/build/html
 
     - uses: peaceiris/actions-gh-pages@v4
       if: ${{ github.event.inputs.deploy }}
       with:
         github_token: ${{ secrets.GITHUB_TOKEN }}
-        publish_dir: ${{ steps.deployment.outputs.artifact }}
+        publish_dir: docs/build/html

docs/requirements.txt

@@ -8,6 +8,7 @@ nbsphinx
 pydata-sphinx-theme
 pygments >=2.12
 pygments-ipython-console
+setuptools-scm
 sphinx
 sphinx-design
 sphinx-tabs

docs/source/api/_bss_dm.rst

@@ -1,10 +1,11 @@
 .. _bss_dm:
 
-APS DM interface to APS IS Scheduling System
-============================================
+APS DM interface
+================
 
-This interface does not require credentials for its use at APS.  Fewer proposal
-details are available than the :ref:`direct IS interface <bss_is>`.
+This APS DM interface to the APS IS Scheduling System does not require
+credentials for its use at APS.  Fewer proposal details are available than the
+:ref:`direct IS interface <bss_is>`.
 
 .. automodule:: apsbss.bss_dm
     :members:

docs/source/api/index.rst

@@ -1,4 +1,4 @@
-.. _beamtime_source_docs:
+.. _api:
 
 API
 ===

docs/source/apsbss.rst

@@ -96,8 +96,7 @@ The ``-v`` option prints the program version.  The ``-h`` option prints the help
 Subcommands
 ===========
 
-See :ref:`beamtime_source_docs` for the source code documentation of each of these
-  subcommands.
+See :ref:`api` for the source code documentation of each of these subcommands.
 
 .. _subcommand.beamlines:
 
@@ -874,4 +873,4 @@ Downloads
 Source code documentation
 ---------------------------
 
-See :ref:`beamtime_source_docs` for the source code documentation.
+See :ref:`api` for the source code documentation.

docs/source/changes.rst

@@ -1,3 +1,5 @@
+.. _changes:
+
 ..
 	CHANGES
 	=======

docs/source/conf.py

@@ -23,7 +23,7 @@
 gh_org = "BCDA-APS"
 project = metadata["name"]
 copyright = toml["tool"]["copyright"]["copyright"]
-author = ", ".join([a["name"] for a in metadata["authors"]])
+author = metadata["authors"][0]["name"]
 description = metadata["description"]
 rst_prolog = f".. |author| replace:: {author}"
 github_url = f"https://github.com/{gh_org}/{project}"
@@ -42,6 +42,7 @@
     sphinx.ext.mathjax
     sphinx.ext.todo
     sphinx.ext.viewcode
+    sphinx_design
 """.split()
 
 templates_path = ["_templates"]

docs/source/index.rst

@@ -10,30 +10,51 @@ apsbss
 Read-only interface to information from APS Proposal and ESAF (experiment safety
 approval form) databases.
 
-Package Information
--------------------
+.. icons: https://fonts.google.com/icons
 
-:full version: |release|
-:published: |today|
-:copyright: 2017-2025, UChicago Argonne, LLC
-:license: ANL OPEN SOURCE LICENSE (see LICENSE.txt file)
-:author: Pete R. Jemian <[email protected]>
+.. grid:: 2
+
+    .. grid-item-card:: :material-regular:`install_desktop;3em` :ref:`Install <install>`
+
+      Install the ``apsbss`` package and get started.
+
+    .. grid-item-card:: :material-regular:`apps;3em` :ref:`apsbss_application`
+
+      ``apsbss``, the command-line program.
+
+    .. grid-item-card:: :material-regular:`precision_manufacturing;3em` :ref:`apsbss_ioc`
+
+      (optional) The local EPICS IOC.
+
+    .. grid-item-card:: :material-regular:`subscriptions;3em` :ref:`api`
+
+      Source-code documentation.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
-   :glob:
+   :hidden:
 
    install
    apsbss
    ioc
    api/index
+
    changes
    license
 
-Indices and tables
-==================
+About
+-----
+
+:home: https://bcda-aps.github.io/apsbss
+:source: https://github.com/bcda-aps/apsbss
+:full version: |release|
+:published: |today|
+:revisions: :ref:`History of code changes <changes>`
+:copyright: 2017-2025, UChicago Argonne, LLC
+:license: :ref:`ANL OPEN SOURCE LICENSE <license>` (see LICENSE.txt file)
+:author: Pete R. Jemian <[email protected]>
+:index: :ref:`genindex`
 
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`

pyproject.toml

@@ -1,16 +1,23 @@
 [build-system]
-requires = ["setuptools>=64", "setuptools_scm[toml]>=8"]
 build-backend = "setuptools.build_meta"
+requires = [
+  "setuptools_scm[toml]>=8",
+  "setuptools>=64",
+]
 
 [project]
 name = "apsbss"
-description = "Get information from APS Beamline Scheduling System."
-authors = [{ name = "Pete Jemian", email = "[email protected]" }]
-maintainers = [{ name = "Pete Jemian", email = "[email protected]" }]
 dynamic = ["version"]
+description = "Get information from APS Beamline Scheduling System."
+authors = [
+  { name = "Pete Jemian", email = "[email protected]" }
+]
+maintainers = [
+  { name = "Pete Jemian", email = "[email protected]" }
+]
 readme = "README.md"
 requires-python = ">=3.9"
-keywords = ["APS", "BSS", "ESAF", "Proposal"]
+keywords = ["APS", "BSS", "ESAF", "Proposal", "EPICS"]
 # https://packaging.python.org/en/latest/specifications/declaring-project-metadata/?highlight=license
 license = { file = "LICENSE.txt" }
 # https://pypi.org/classifiers/
@@ -58,11 +65,13 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
   "build",
+  "caproto",
   "coverage",
   "ipython",
   "isort",
   "mypy",
   "pre-commit",
+  "pyepics",
   "pytest",
   "ruff",
 ]
@@ -80,28 +89,42 @@ doc = [
 
 all = ["apsbss[dev,doc]"]
 
+[project.scripts]
+apsbss = "apsbss.apsbss:main"
+apsbss_makedb = "apsbss.apsbss_makedb:main"
+# TODO apsbss_ioc.sh
 
 [project.urls]
 "Homepage" = "https://BCDA-APS.github.io/apsbss"
 "Bug Tracker" = "https://github.com/BCDA-APS/apsbss/issues"
 
-[project.scripts]
-apsbss = "apsbss.apsbss:main"
-
 [tool.black]
 line-length = 115
+target-version = ['py311']
+include = '\.pyi?$'
 
 [tool.copyright]
 copyright = "2017-2025, UChicago Argonne, LLC"
 
 [tool.flake8]
 max-line-length = 115
-extend-ignore = ["E226", "E402", "E501", "E741", "F401", "F403", "W503", "W504"]
+extend-ignore = [
+  "E226",
+  "E402", # module level import not at top of file (for cansas.py)
+  "E501",
+  "E741",
+  "F401",  # imported but unused
+  "F403",
+  "W503",
+  "W504",
+]
 
 [tool.isort]
-force_single_line = true
-# multi_line_output = 1
-line_length = 115
+force_single_line  = "True"
+include_trailing_comma = true
+multi_line_output = "NOQA"
+profile = "black"
+src_paths = ["apsbss"]
 
 [tool.pytest.ini_options]
 addopts = ["--import-mode=importlib", "-x"]
@@ -137,6 +160,19 @@ indent-width = 4
 # Assume Python 3.11
 target-version = "py311"
 
+[tool.ruff.format]
+# Like Black, use double quotes for strings.
+quote-style = "double"
+
+# Like Black, indent with spaces, rather than tabs.
+indent-style = "space"
+
+# Like Black, respect magic trailing commas.
+skip-magic-trailing-comma = false
+
+# Like Black, automatically detect the appropriate line ending.
+line-ending = "auto"
+
 [tool.ruff.lint]
 # Enable Pyflakes (`F`) and a subset of the pycodestyle (`E`)  codes by default.
 select = [
@@ -195,23 +231,12 @@ dummy-variable-rgx = "^(_+|(_+[a-zA-Z0-9_]*[a-zA-Z0-9]+?))$"
 [tool.ruff.lint.isort]
 force-single-line = true # Enforces single-line imports
 
-[tool.ruff.format]
-# Like Black, use double quotes for strings.
-quote-style = "double"
-
-# Like Black, indent with spaces, rather than tabs.
-indent-style = "space"
-
-# Like Black, respect magic trailing commas.
-skip-magic-trailing-comma = false
-
-# Like Black, automatically detect the appropriate line ending.
-line-ending = "auto"
-
 [tool.setuptools]
-package-dir = { "apsbss" = "apsbss" }
+# package-dir = { "apsbss" = "apsbss" }
+py-modules = ["apsbss"]
 
 [tool.setuptools.package-data]
 "*" = ["*.yml"]
 
 [tool.setuptools_scm]
+write_to = "apsbss/_version.py"