DM-44144: Make sconsUtils standalone/pip-installable

.github/workflows/build.yaml

@@ -7,11 +7,11 @@ on:
   pull_request:
 
 jobs:
-  build_and_test:
+  build_and_test_conda:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest]
-        pyversion: ["3.11", "3.12", "3.13", "3.14"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
 
     runs-on: ${{ matrix.os }}
     steps:
@@ -54,3 +54,110 @@ jobs:
         with:
           files: tests/.tests/pytest-sconsUtils.xml-cov-sconsUtils.xml
           token: ${{ secrets.CODECOV_TOKEN }}
+  build_and_test_pip:
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
+
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Need to clone everything for the git tags.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: "pip"
+          cache-dependency-path: "setup.cfg"
+          allow-prereleases: true
+
+      - name: Install dependencies
+        shell: bash -l {0}
+        run: |
+          pip install --upgrade pip uv
+          uv pip install --system -r requirements.txt
+
+      # We have two cores so we can speed up the testing with xdist
+      - name: Install pytest packages
+        shell: bash -l {0}
+        run: |
+          uv pip install --system pytest pytest-xdist
+
+      - name: Build and install
+        run: |
+          uv pip install --system --no-deps -v -e .
+
+      - name: Run tests
+        run: |
+          pytest --ignore=tests/test_simple.py -r a -v -n 3
+          scons -j2
+
+  check-changes:
+    outputs:
+      skip: ${{ steps.check.outputs.skip }}
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/')
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - name: Check if weekly changed
+        id: check
+        run: |
+          # Get SHA hashes for all weekly tags
+          weekly_sha=$(git tag -l 'w.*' | while read tag; do
+            git rev-list -n 1 "${tag}"
+          done)
+
+          echo "Weekly tag SHA ${weekly_sha}"
+          # Extract the current tag and its SHA
+          current_tag=${GITHUB_REF#refs/tags/}
+          echo "Current tag: ${current_tag}"
+          current_sha=$(git rev-list -1 "${current_tag}") || echo "no_value"
+          echo "Current sha: ${current_sha}"
+          # Count occurrences of the current SHA in the weekly SHA list
+          n=$(echo "${weekly_sha}" | grep -c "${current_sha}") || echo "0"
+          echo "Current tag ${current_tag} (${current_sha}) SHA found ${n} time(s)"
+
+          # Determine whether to skip the upload based on the count
+          if [ "${n}" -gt 1 ]; then
+            echo "Skip upload"
+            echo "skip=true" >> "${GITHUB_OUTPUT}"
+          else
+            echo "Enable upload"
+            echo "skip=false" >> "${GITHUB_OUTPUT}"
+          fi
+
+  pypi:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    needs: [build_and_test_conda, build_and_test_pip, check-changes]
+    permissions:
+      id-token: write
+    if: "${{ ! startsWith(github.ref, 'refs/tags/w.') || needs.check-changes.outputs.skip == 'false' }}"
+
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Need to clone everything to embed the version.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install --upgrade setuptools wheel build
+
+      - name: Build and create distribution
+        run: |
+          python -m build --skip-dependency-check
+
+      - name: Upload
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/build_docs.yaml

@@ -0,0 +1,45 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  build_sphinx_docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          # Need to clone everything for the git tags.
+          fetch-depth: 0
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+          cache: "pip"
+          cache-dependency-path: "setup.cfg"
+
+      - name: Install graphviz
+        run: sudo apt-get install graphviz
+
+      - name: Update pip/wheel infrastructure
+        run: |
+          python -m pip install --upgrade pip uv
+          uv pip install --system wheel
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -r requirements.txt
+
+      - name: Build and install
+        run: uv pip install --system --no-deps -v .
+
+      - name: Install documenteer
+        run: uv pip install --system -r doc/requirements.txt
+
+      - name: Build documentation
+        working-directory: ./doc
+        run: package-docs build

.gitignore

@@ -6,21 +6,36 @@ config.log
 _build.log
 _build.sh
 _build.tags
+
 *.o
 *.os
 *.so
 *.cfgc
 *.pyc
 pytest_session.txt
+
+# Built by sconsUtils
 bin/
-bin/makeLinkFarm
-bin/sconsOpts
 python/lsst/sconsUtils/version.py
+
+# Built by pip install
+python/lsst_sconsUtils.egg-info/
+
+# docs
+doc/api
 doc/html
 doc/doxygen.conf
 doc/sconsUtils.tag
+
+# Pytest
 tests/.tests
 tests/testFailedTests/python
 tests/testFailedTests/tests/.tests
 .coverage
 python/*.dist-info/
+
+dist/
+
+# IDEs
+.idea
+.vscode

COPYRIGHT

@@ -0,0 +1,2 @@
+Copyright 2024 Association of Universities for Research in Astronomy, Inc. (AURA)
+Copyright 2024 The Trustees of Princeton University

LICENSE

@@ -0,0 +1,3 @@
+This software is dual licensed under the GNU General Public License and also
+under a 3-clause BSD license. Recipients may choose which of these licenses
+to use; please see the files gpl-3.0.txt and/or bsd_license.txt, respectively.

README.md

@@ -0,0 +1,21 @@
+# lsst-sconsUtils
+
+[![codecov](https://codecov.io/gh/lsst/sconsUtils/branch/main/graph/badge.svg?token=2BUBL8R9RH)](https://codecov.io/gh/lsst/sconsUtils)
+
+sconsUtils is a package in the [LSST Science Pipelines](https://pipelines.lsst.io/).
+
+This package contains utility scripts for building pipelines packages with
+[SCons](https://scons.org/), and is required to build most pipelines packages.
+SCons can be used to build C++ and Python (with pybind11 bindings) packages;
+see the [stack package templates](https://github.com/lsst/templates/tree/main/project_templates/stack_package)
+if this is of interest.
+
+This is a **Python 3 only** package.
+
+This software is dual licensed under the GNU General Public License
+(version 3 of the License, or (at your option) any later version),
+and also under a 3-clause BSD license. Recipients may choose which of these
+licenses to use; please see the files gpl-3.0.txt and/or bsd_license.txt,
+respectively.
+
+This package can only be imported through a SCons script.

bsd_license.txt

@@ -0,0 +1,27 @@
+For copyright information see the COPYRIGHT file included in the top-level
+directory of this distribution.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+     1. Redistributions of source code must retain the above copyright notice,
+        this list of conditions and the following disclaimer.
+
+     2. Redistributions in binary form must reproduce the above copyright
+        notice, this list of conditions and the following disclaimer in the
+        documentation and/or other materials provided with the distribution.
+
+     3. Neither the names of the copyright holders nor the names of their
+        contributors may be used to endorse or promote products derived from
+        this software without specific prior written permission.
+
+ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+ WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+ DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
+ FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+ DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+ CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+ OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

doc/conf.py

@@ -24,11 +24,8 @@
 
 This configuration only affects single-package Sphinx documentation builds.
 """
+# ruff: noqa: F403, F405
 
-from documenteer.conf.pipelinespkg import *  # noqa: F403, import *
+from documenteer.conf.guide import *
 
-project = "sconsUtils"
-html_theme_options["logotext"] = project  # noqa: F405, unknown name
-html_title = project
-html_short_title = project
-doxylink = {}
+exclude_patterns.append("changes/*")

doc/documenteer.toml

@@ -0,0 +1,19 @@
+[project]
+title = "lsst-sconsUtils"
+
+[project.python]
+package = "lsst-sconsUtils"
+
+[build]
+clean = true
+
+[sphinx]
+
+nitpick_ignore = [
+]
+nitpick_ignore_regex = [
+]
+
+[sphinx.intersphinx.projects]
+python = "https://docs.python.org/3"
+scons = "https://scons.org/doc/4.10.0/HTML/scons-api/"

doc/lsst.sconsUtils/index.rst

@@ -16,7 +16,7 @@ Contributing
 ============
 
 ``lsst.sconsUtils`` is developed at https://github.com/lsst/sconsUtils.
-You can find Jira issues for this module under the `sconsUtils <https://jira.lsstcorp.org/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20sconsUtils>`_ component.
+You can find Jira issues for this module under the `sconsUtils <https://rubinobs.atlassian.net/issues/?jql=project%20%3D%20DM%20AND%20component%20%3D%20sconsUtils>`_ component.
 
 .. _lsst.sconsUtils-pyapi:
 
@@ -34,11 +34,13 @@ Python API reference
    :no-inheritance-diagram:
 .. automodapi:: lsst.sconsUtils.dependencies
    :no-main-docstr:
+   :no-inheritance-diagram:
 .. automodapi:: lsst.sconsUtils.tests
    :no-main-docstr:
    :no-inheritance-diagram:
 .. automodapi:: lsst.sconsUtils.installation
    :no-main-docstr:
+   :no-inheritance-diagram:
 .. automodapi:: lsst.sconsUtils.builders
    :no-main-docstr:
    :no-inheritance-diagram:

doc/requirements.txt

@@ -0,0 +1 @@
+lsst-sphinxutils @ git+https://github.com/lsst/sphinxutils@main