From df9cd9df6b530515a5a9e12871629f60acf98acd Mon Sep 17 00:00:00 2001 From: Prakriti Gupta Date: Tue, 16 Jun 2026 15:58:43 -0700 Subject: [PATCH] Fix Sphinx build and add workflow for Sphinx website --- .github/workflows/docs.yml | 58 ++++ .gitignore | 38 +-- doc/build/autoinstall.yaml | 292 ------------------ .../build_notes}/fei_server_build_notes.rst | 8 +- .../build_notes}/host_machine_build_notes.rst | 26 +- .../build_notes}/rtc_buildnote.rst | 30 +- docs/conf.py | 36 +++ docs/index.rst | 38 +++ docs/requirements.txt | 3 + 9 files changed, 180 insertions(+), 349 deletions(-) create mode 100644 .github/workflows/docs.yml delete mode 100644 doc/build/autoinstall.yaml rename {doc/build => docs/build_notes}/fei_server_build_notes.rst (99%) rename {doc/build => docs/build_notes}/host_machine_build_notes.rst (93%) rename {doc/build => docs/build_notes}/rtc_buildnote.rst (88%) create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/requirements.txt diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..40a9be3 --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,58 @@ +name: Docs + +on: + push: + branches: ["main"] + pull_request: + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + build-docs: + runs-on: ubuntu-latest + + steps: + - name: Check out repository + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.12" + + - name: Install docs dependencies + run: | + python -m pip install -U pip + python -m pip install -r docs/requirements.txt + + - name: Build Sphinx docs + run: | + python -m sphinx -b html -W --keep-going docs docs/_build/html + touch docs/_build/html/.nojekyll + + - name: Upload Pages artifact + uses: actions/upload-pages-artifact@v3 + with: + path: docs/_build/html + + deploy: + if: github.event_name == 'push' + needs: build-docs + runs-on: ubuntu-latest + + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.gitignore b/.gitignore index 1681eb4..9924d0c 100644 --- a/.gitignore +++ b/.gitignore @@ -27,8 +27,6 @@ share/python-wheels/ MANIFEST # PyInstaller -# Usually these files are written by a python script from a template -# before PyInstaller builds the exe, so as to inject date/other infos into it. *.manifest *.spec @@ -69,7 +67,16 @@ instance/ .scrapy # Sphinx documentation -docs/_build/ +# Keep source files in docs/ tracked, but ignore generated build output. +/docs/_build/ +/docs/.doctrees/ +/docs/_autosummary/ +/docs/linkcheck/ + +# Legacy Sphinx output locations, in case older commands are used. +/doc/_build/ +/doc/build/html/ +/doc/build/doctrees/ # PyBuilder .pybuilder/ @@ -83,35 +90,20 @@ profile_default/ ipython_config.py # pyenv -# For a library or package, you might want to ignore these files since the code is -# intended to run in multiple environments; otherwise, check them in: # .python-version # pipenv -# According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control. -# However, in case of collaboration, if having platform-specific dependencies or dependencies -# having no cross-platform support, pipenv may install dependencies that don't work, or not -# install all needed dependencies. -#Pipfile.lock +# Pipfile.lock # poetry -# Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control. -# This is especially recommended for binary packages to ensure reproducibility, and is more -# commonly ignored for libraries. -# https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control -#poetry.lock +# poetry.lock # pdm -# Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control. -#pdm.lock -# pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it -# in version control. -# https://pdm.fming.dev/latest/usage/project/#working-with-version-control .pdm.toml .pdm-python .pdm-build/ -# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm +# PEP 582 __pypackages__/ # Celery stuff @@ -155,10 +147,6 @@ dmypy.json cython_debug/ # PyCharm -# JetBrains specific template is maintained in a separate JetBrains.gitignore that can -# be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore -# and can be added to the global gitignore or merged into this file. For a more nuclear -# option (not recommended) you can uncomment the following to ignore the entire idea folder. .idea/ # MacOS diff --git a/doc/build/autoinstall.yaml b/doc/build/autoinstall.yaml deleted file mode 100644 index cade59d..0000000 --- a/doc/build/autoinstall.yaml +++ /dev/null @@ -1,292 +0,0 @@ -# 2026-01-08 -# -# Created by Chris Johnson (CAJ) at the UCLA Infrared Laboratory. -# -# NOTE: The installation will FAIL if some settings are not modified. Please read below! -# -# This autoinstall assumes that the system uses the eno1np0 network interface -# like the ASLab Lancelot systems purchased for the HISPEC Project. -# -# An internet connection is required for the installation to complete successfully. -# Building a custom ISO is outside the scope of this project. -# -# This build will install to the *smallest* storage disk available (this is opposite -# from the default). -# -# CAJ: Basic Instructions -# 1. Download the Ubuntu Server ISO: https://ubuntu.com/download/server -# 2. Create a USB stick for the installation using whatever method desired. -# a. My preferred method is using Rufus on a Windows PC. -# 3. Copy this file, autoinstall.yaml, to the root of the USB Drive. -# 4. Complete the OPTIONAL steps below if desired. -# 5. *** MANDATORY ***: Modify the settings labled with MODIFY below. -# 6. Boot the USB stick and Ubuntu should install with no user input! -# Install takes about XX minutes: (Started at 14:00) -# -# CAJ: WARNING: Ubuntu's autoinstall file is very sensitive to syntax. -# A single character out of place can cause the installation to fail. -# -# SSH keys can be added to each account, and to the root account. -# By default, the root account will not allow login even with SSH. -# This is a good security measure to leave in. -# -# If there are network setup and/or storage issues while setting up, -# These can be specified as interactive during the installation. -# -# CAJ: To speed up the process, you can modify grub to reduce the timeout -# from 30 seconds to 5 seconds (or less). -# [OPTIONAL] -# -# CAJ: Unless the keyword "autoinstall" is added to the boot line, then -# the installation will pause and prompt the user to continue. -# [OPTIONAL] -# -# diff grub.cfg grub.cfg.autoinstall -#1c1 -#< set timeout=30 -#--- -#> set timeout=5 -#10c10 -#< linux /casper/vmlinuz --- -#--- -#> linux /casper/vmlinuz autoinstall --- -# -# CAJ: Set default passwords for every user to "hispec". -# To create a password for an account: openssl passwd -6 hispec -# -# CAJ: To-Do -# 1. Create a post-install script to automate some tasks. -# -#cloud-config -# See the autoinstall documentation at: -# https://canonical-subiquity.readthedocs-hosted.com/en/latest/reference/autoinstall-reference.html -autoinstall: - active-directory: - admin-name: '' - domain-name: '' - apt: - disable_components: [] - fallback: offline-install - geoip: true - mirror-selection: - primary: - - country-mirror - - arches: - - amd64 - - i386 - uri: http://archive.ubuntu.com/ubuntu/ - - arches: - - s390x - - arm64 - - armhf - - powerpc - - ppc64el - - riscv64 - uri: http://ports.ubuntu.com/ubuntu-ports - preserve_sources_list: false - security: - - arches: - - amd64 - - i386 - uri: http://security.ubuntu.com/ubuntu/ - - arches: - - s390x - - arm64 - - armhf - - powerpc - - ppc64el - - riscv64 - uri: http://ports.ubuntu.com/ubuntu-ports - codecs: - install: false - drivers: - install: false - kernel: - package: linux-generic-hwe-24.04 - keyboard: - layout: us - toggle: null - variant: '' - locale: en_US.UTF-8 - network: - ethernets: - all-en: - match: - name: "en*" - addresses: - - 192.168.29.222/24 # MODIFY: Change IP as required. MUST provide Internet - nameservers: - addresses: - - 192.168.29.254 # MODIFY: Change DNS as required - search: - - caltech.edu # MODIFY: Change DNS search suffixes as required - # - astro.ucla.edu - # - keck.hawaii.edu - routes: - - to: default - via: 192.168.29.254 # MODIFY: Change gateway as required - version: 2 - oem: - install: auto - packages: - # Essential Build Tools - - autoconf - - build-essential - - flex - - flex-doc - - bison - - bison-doc - # - curl # Already installed by default - # - git # Already installed by default - - groff - - libc6-dev-i386 # NOT lib32c-dev - - libbz2-dev - - libffi-dev - - liblzma-dev - - libmotif-dev - - libncurses-dev # NOT libncursesw5-dev - - libreadline-dev - - libsqlite3-dev - - libssl-dev - - libxml2-dev - - libxmlsec1-dev - - llvm - - make - - m4 - - pandoc - - pyqt5-dev-tools - - python3-dev - - python3-docutils - - python3-pil.imagetk - - python3-pip - - python3-tk - - python3-venv - - rst2pdf - - snmp - - software-properties-common - - tk-dev - # - wget # Already installed by default - - xaw3dg-dev - - xorg-dev - # - xz-utils # Already installed by default - - zlib1g-dev - # KROOT Specific Packages - - openconnect - - subversion - - cvs - - at - # - libxt-dev # Already installed by default - # - libncurses-dev # Already installed by default - # - tcl # Already installed by default - # - tcl-dev # Already installed by default - - tcl-thread - - tcllib - # - tk # Already installed by default - # - tk-dev # Already installed by default - - expect - - tclx8.4 # NOT tclx - - tcl-fitstcl - - libpq-dev - # - g++ # Already installed by default - - gfortran - - libpam0g-dev # NOT libpam-dev - - python3-ephem - # Additional Instrument Development Packages - - libboost-all-dev - - libopencv-dev - - libccfits-dev - - libcfitsio-dev - # CAJ: Install for Testing - # - virt-manager - # - smartmontools - source: - id: ubuntu-server - search_drivers: false - ssh: - allow-pw: true - authorized-keys: - - 'ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPqrTAPHTxP6ECM/bFR2tBTwdCWHJEYwEBntvu1ted5v - chrisaj5@github/127692781 # ssh-import-id gh:chrisaj5' - install-server: true -# interactive-sections: -#- storage - storage: - layout: - name: direct - match: - size: smallest - timezone: America/Los_Angeles - updates: security - user-data: - hostname: hscomputer # MODIFY: Change this to proper system name - users: - - gecos: HISPEC Main - groups: - - adm - - cdrom - - sudo - - dip - - plugdev - - lxd - lock_passwd: false - name: hispec - passwd: $6$rMGXJxmN5OxnsaVm$eoFq44czpnmCkCIJ6k3FSRDgmZrogXGaB/2U2KxrwGx6s59AlZaCF0b5bU4oHwAP3sEWzpf8GKBlodBKIqt/P1 - shell: /bin/bash - ssh_authorized_keys: - - ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIPqrTAPHTxP6ECM/bFR2tBTwdCWHJEYwEBntvu1ted5v - johnsonc@t3.astro.ucla.edu - - gecos: HISPEC Dev - groups: - - adm - - cdrom - - sudo - - dip - - plugdev - - lxd - - dialout - lock_passwd: false - name: hsdev - passwd: $6$rMGXJxmN5OxnsaVm$eoFq44czpnmCkCIJ6k3FSRDgmZrogXGaB/2U2KxrwGx6s59AlZaCF0b5bU4oHwAP3sEWzpf8GKBlodBKIqt/P1 - shell: /bin/bash - - gecos: HISPEC Bld - groups: - - adm - - cdrom - - sudo - - dip - - plugdev - - lxd - - dialout - lock_passwd: false - name: hispecbld - passwd: $6$rMGXJxmN5OxnsaVm$eoFq44czpnmCkCIJ6k3FSRDgmZrogXGaB/2U2KxrwGx6s59AlZaCF0b5bU4oHwAP3sEWzpf8GKBlodBKIqt/P1 - shell: /bin/bash - - gecos: HISPEC Eng - groups: - - adm - - cdrom - - sudo - - dip - - plugdev - - lxd - - dialout - lock_passwd: false - name: hispeceng - passwd: $6$rMGXJxmN5OxnsaVm$eoFq44czpnmCkCIJ6k3FSRDgmZrogXGaB/2U2KxrwGx6s59AlZaCF0b5bU4oHwAP3sEWzpf8GKBlodBKIqt/P1 - shell: /bin/bash - - gecos: HISPEC Run - groups: - - adm - - cdrom - - sudo - - dip - - plugdev - - lxd - - dialout - lock_passwd: false - name: hispecrun - passwd: $6$rMGXJxmN5OxnsaVm$eoFq44czpnmCkCIJ6k3FSRDgmZrogXGaB/2U2KxrwGx6s59AlZaCF0b5bU4oHwAP3sEWzpf8GKBlodBKIqt/P1 - shell: /bin/bash - late-commands: - - curtin in-target -- groupadd -g 2001 instr - version: 1 diff --git a/doc/build/fei_server_build_notes.rst b/docs/build_notes/fei_server_build_notes.rst similarity index 99% rename from doc/build/fei_server_build_notes.rst rename to docs/build_notes/fei_server_build_notes.rst index 211d026..9e1fd48 100644 --- a/doc/build/fei_server_build_notes.rst +++ b/docs/build_notes/fei_server_build_notes.rst @@ -10,7 +10,7 @@ System Requirements User and Hostname Setup -======================= +----------------------- Create a development user ``hsdev`` and facility user ``hispecfei``: @@ -67,7 +67,7 @@ Notes Group and Account Setup -======================= +----------------------- Create required groups for HISPEC development: @@ -499,10 +499,10 @@ OS Optimization Notes (07/09/2025) Final Step -========== +---------- **RESTART/REBOOT** the server to complete driver installation and apply CPU/OS optimization changes. Done! -===== +----- diff --git a/doc/build/host_machine_build_notes.rst b/docs/build_notes/host_machine_build_notes.rst similarity index 93% rename from doc/build/host_machine_build_notes.rst rename to docs/build_notes/host_machine_build_notes.rst index 8a7b100..9307bbd 100644 --- a/doc/build/host_machine_build_notes.rst +++ b/docs/build_notes/host_machine_build_notes.rst @@ -3,13 +3,13 @@ Build Setup for hsdev User =========================================== System Requirements -==================== +------------------- - OS: Ubuntu 24.04 LTS - Python: 3.12 (default system version) User Setup -========== +---------- Create a development user ``hsdev``: @@ -20,7 +20,7 @@ Create a development user ``hsdev``: sudo usermod -aG dialout hsdev # Add serial access group Group and Account Setup -======================== +----------------------- Create required groups for HISPEC development: @@ -51,7 +51,7 @@ Create standard HISPEC accounts (if not already provisioned): done System Package Installation -=========================== +--------------------------- Update package list and install the essential build tools: @@ -93,7 +93,7 @@ Update package list and install the essential build tools: pandoc groff rst2pdf KROOT Specific Packages --------------------------- +~~~~~~~~~~~~~~~~~~~~~~~ These packages are needed for KROOT environments: @@ -110,7 +110,7 @@ These packages are needed for KROOT environments: python3-ephem Additional Instrument Development Packages ------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash @@ -121,7 +121,7 @@ Additional Instrument Development Packages libcfitsio-dev Python Package Installation -=========================== +--------------------------- Use Python 3.12 (default) and install required Python packages: @@ -138,7 +138,7 @@ Verify installation: pip3 list Optional: Virtual Environment -============================= +----------------------------- Create and activate a virtual environment: @@ -149,7 +149,7 @@ Create and activate a virtual environment: pip install numpy matplotlib pipython Directory Structure -=================== +------------------- The following directory structure is recommended: @@ -168,7 +168,7 @@ Create the directories: chown -R hsdev:hsdev /home/hsdev/external /home/hsdev/svn External Development Libraries -============================== +------------------------------ For third-party libraries, build and install them under ``/home/hsdev/external``: @@ -182,7 +182,7 @@ For third-party libraries, build and install them under ``/home/hsdev/external`` make && make install Update Hosts File -================= +----------------- The private network for HISPEC is ``192.168.29.x``. Edit the ``/etc/hosts`` file and add the following entries: @@ -204,7 +204,7 @@ Edit the ``/etc/hosts`` file and add the following entries: 192.168.29.154 hs1wireblue Disable Unnecessary Services -============================ +---------------------------- To reduce background system noise or services not needed in headless/dev setups: @@ -218,6 +218,6 @@ To reduce background system noise or services not needed in headless/dev setups: sudo systemctl disable avahi-daemon.service # Zeroconf mDNS Done! -===== +----- System is now prepared for development under the ``hsdev`` user. diff --git a/doc/build/rtc_buildnote.rst b/docs/build_notes/rtc_buildnote.rst similarity index 88% rename from doc/build/rtc_buildnote.rst rename to docs/build_notes/rtc_buildnote.rst index 1fed993..5da5c13 100644 --- a/doc/build/rtc_buildnote.rst +++ b/docs/build_notes/rtc_buildnote.rst @@ -8,18 +8,18 @@ System Build: TCC & Real-Time Kernel :System Name: hsfei 1. Prerequisites & Media Preparation -==================================== +------------------------------------ To ensure a clean environment, all drives were erased before starting the **0% -> 100% build**. USB Drive A: Ubuntu Installer ------------------------------ +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **OS:** Ubuntu Server 24.04.1 LTS * **Source:** Official Ubuntu Download * **Format:** Bootable ISO USB Drive B: Cloud-Init (CIDATA) --------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ * **Format:** FAT32 * **Volume Name:** ``CIDATA`` * **Required Files (Root Directory):** @@ -27,39 +27,39 @@ USB Drive B: Cloud-Init (CIDATA) * ``meta-data``: Empty file (required for boot check). 2. OS Installation (Ubuntu Server 24.04) -======================================== +---------------------------------------- *Note: Due to issues with the automated installation, the manual method was used.* Installation Parameters ------------------------ +~~~~~~~~~~~~~~~~~~~~~~~ * **Language/Keyboard:** English * **Networking:** Ethernet connected; No Proxy. * **Mirror:** ``[http://us.archive.ubuntu.com/ubuntu/](http://us.archive.ubuntu.com/ubuntu/)`` (Default) Storage Configuration ---------------------- +~~~~~~~~~~~~~~~~~~~~~ * **Primary Drive:** Samsung 990 Pro (1TB). * **Mount Points:** Temporary format of the 2TB drive as ``ext4``, mounted to ``/usr``. * **Note:** Software RAID 1 was bypassed; to be configured at a later stage. Credentials ------------ +~~~~~~~~~~~ * **Name/Server/User:** ``hsfei`` * **Password:** Set during installation (not documented here for security reasons). * **Software:** Default "Popular Snaps" selected. 3. Post-Install System Hardening -================================ +-------------------------------- Run the following commands immediately after the first boot: System Updates --------------- +~~~~~~~~~~~~~~ .. code-block:: bash sudo apt update && sudo apt upgrade -y Enable Real-Time Kernel ----------------------- +~~~~~~~~~~~~~~~~~~~~~~~ The Real-Time (RT) kernel requires an Ubuntu Pro subscription (using ``elijahab`` account). .. code-block:: bash @@ -71,7 +71,7 @@ The Real-Time (RT) kernel requires an Ubuntu Pro subscription (using ``elijahab` sudo pro enable realtime-kernel CPU Shielding & GRUB Optimization ---------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To optimize performance, 6 cores were shielded to prevent background OS interference. 1. Edit ``/etc/default/grub``: @@ -87,15 +87,15 @@ To optimize performance, 6 cores were shielded to prevent background OS interfer or via codebase affinity settings. 4. TCC Mode (Time Coordinated Computing) -======================================== +---------------------------------------- Enable Sequence ---------------- +~~~~~~~~~~~~~~~ 1. Enter BIOS -> **Enable TCC Mode**. 2. Perform a **Double Reboot** to ensure all hardware settings are applied. 5. Pending Tasks -================ +---------------- * [ ] **Static IP Assignment:** Change from DHCP to ``192.168.29.107``. * [ ] **Software Stack:** Follow GitHub build notes for Python libraries, C++ sources, and hardware drivers. -* [ ] **RAID:** Finalize hardware or software RAID 1 configuration for data drives. \ No newline at end of file +* [ ] **RAID:** Finalize hardware or software RAID 1 configuration for data drives. diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..e82681a --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,36 @@ +"""Sphinx configuration for the HISPEC documentation.""" + +from pathlib import Path +import sys + +ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(ROOT / "src")) + +project = "HISPEC" +author = "Caltech Optical Observatories, UCLA, Keck Observatory" +release = "0.1.0" + +extensions = [ + "myst_parser", +] + +source_suffix = { + ".rst": "restructuredtext", + ".md": "markdown", +} + +master_doc = "index" +templates_path = ["_templates"] +exclude_patterns = [ + "_build", + "Thumbs.db", + ".DS_Store", +] + +html_theme = "shibuya" +html_title = "HISPEC Documentation" +html_static_path = [] +html_theme_options = { + "accent_color": "blue", + "github_url": "https://github.com/CaltechOpticalObservatories/hispec", +} diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..b6b908a --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,38 @@ +HISPEC Documentation +==================== + +HISPEC is a high-resolution near-infrared spectrograph for Keck Observatory. +This documentation site collects the instrument-control software notes, build +procedures, deployment references, and operational information needed by the +engineering team. + +The current documentation is focused on host and subsystem build setup. Each +build note is maintained as its own page so the sidebar can link directly to +the relevant setup procedure. + +Getting Started +--------------- + +Start with the host-machine build page when setting up a development or +deployment machine. Use the FEI server and RTC pages for subsystem-specific +installation and configuration details. + +.. toctree:: + :caption: Build Notes + :maxdepth: 1 + :titlesonly: + + Host Machine Build Setup + FEI Server Build Setup + TCC and Real-Time Kernel Build + +Planned Documentation Areas +--------------------------- + +These sections are placeholders for the next round of documentation pages: + +* software architecture and daemon responsibilities +* configuration and deployment workflow +* hardware interface notes +* operations and troubleshooting procedures +* developer setup and contribution workflow diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..8164a22 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +sphinx>=8,<10 +myst-parser>=4,<6 +shibuya>=2026.1.9