Merge 7098eeb into da1060a

.github/workflows/python-package.yml

@@ -17,7 +17,7 @@ jobs:
             fail-fast: true
             matrix:
                 os: [ubuntu-latest]
-                python-version: ['3.8', '3.9', '3.10']
+                python-version: ['3.8', '3.9', '3.10']  # , '3.11'] Astropy 5.0 may be incompatible with Python 3.11
                 numpy-version: ['<1.23']
                 astropy-version: ['==5.0', '<5.1', '<6.0']
 
@@ -33,11 +33,9 @@ jobs:
             - name: Install Python dependencies
               run: |
                 python -m pip install --upgrade pip wheel
-                python -m pip install pytest
-                if [ -f requirements.txt ]; then pip install -r requirements.txt; pip install .; fi
-                pip install -U "numpy${{ matrix.numpy-version }}"
-                pip install -U "astropy${{ matrix.astropy-version }}"
-#                if [ "${{ matrix.astropy-version }}" = "<3.0" ]; then pip install -U "healpy==1.12.9"; fi
+                python -m pip install --upgrade "numpy${{ matrix.numpy-version }}"
+                python -m pip install --upgrade "astropy${{ matrix.astropy-version }}"
+                python -m pip install --editable .[test]
             - name: Run the test
               run: pytest
 
@@ -48,7 +46,7 @@ jobs:
             fail-fast: false
             matrix:
                 os: [ubuntu-latest]
-                python-version: ['3.9']
+                python-version: ['3.10']
                 astropy-version: ['<5.1']
 
         steps:
@@ -63,9 +61,7 @@ jobs:
             - name: Install Python dependencies
               run: |
                 python -m pip install --upgrade pip wheel
-                python -m pip install pytest pytest-cov coveralls
-                if [ -f requirements.txt ]; then pip install -r requirements.txt; pip install .; fi
-                pip install -U "astropy${{ matrix.astropy-version }}"
+                python -m pip install --editable .[coverage]
             - name: Run the test with coverage
               run: pytest --cov
             - name: Coveralls
@@ -81,7 +77,7 @@ jobs:
             fail-fast: false
             matrix:
                 os: [ubuntu-latest]
-                python-version: ['3.9']
+                python-version: ['3.10']
 
         steps:
             - name: Checkout code
@@ -93,7 +89,7 @@ jobs:
               with:
                 python-version: ${{ matrix.python-version }}
             - name: Install Python dependencies
-              run: python -m pip install --upgrade pip wheel Sphinx
+              run: python -m pip install --upgrade pip wheel Sphinx sphinx-rtd-theme
             - name: Test the documentation
               run: sphinx-build -W --keep-going -b html doc doc/_build/html
 
@@ -104,7 +100,7 @@ jobs:
             fail-fast: false
             matrix:
                 os: [ubuntu-latest]
-                python-version: ['3.9']
+                python-version: ['3.10']
 
         steps:
             - name: Checkout code
@@ -119,5 +115,5 @@ jobs:
               run: python -m pip install --upgrade pip wheel pycodestyle
             - name: Test the style; failures are allowed
               # This is equivalent to an allowed falure.
-              continue-on-error: true
+              # continue-on-error: true
               run: pycodestyle --count py/desiutil

MANIFEST.in

@@ -1,12 +1,2 @@
-include LICENSE.rst
-include README.rst
-include requirements.txt
-
-graft bin
-graft doc
-graft etc
-
-prune build
-prune dist
-prune htmlcov
-prune doc/_build
+prune .github
+global-exclude .gitignore .readthedocs.yml

bin/desi_data_census → bin/desi_api_file

@@ -2,5 +2,5 @@
 # -*- coding: utf-8 -*-
 # Licensed under a 3-clause BSD style license - see LICENSE.rst
 from sys import exit
-from desiutil.census import main
+from desiutil.api import main
 exit(main())

bin/desi_module_file

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+from sys import exit
+from desiutil.modules import main
+exit(main())

bin/desi_update_version

@@ -0,0 +1,6 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
+# Licensed under a 3-clause BSD style license - see LICENSE.rst
+from sys import exit
+from desiutil.setup import main
+exit(main())

doc/Makefile

@@ -2,7 +2,7 @@
 #
 
 # You can set these variables from the command line.
-SPHINXOPTS    =
+SPHINXOPTS    = -W --keep-going
 # For macports, use the second line...
 SPHINXBUILD   = sphinx-build
 # SPHINXBUILD   = sphinx-build-2.7

doc/api.rst

@@ -5,6 +5,9 @@ desiutil API
 .. automodule:: desiutil
     :members:
 
+.. automodule:: desiutil.api
+    :members:
+
 .. automodule:: desiutil.bitmask
     :members:
 

doc/helpers.rst

@@ -0,0 +1,190 @@
+==============
+Helper Scripts
+==============
+
+Python Scripts
+==============
+
+API Generation
+--------------
+
+:command:`desi_api_file` creates an API file for a DESI software product.
+The command is meant to be run in a git clone (or svn checkout) of a software
+product.  It creates ``doc/api.rst``, with a link to every ``*.py`` file in the
+software product.
+
+Example::
+
+    git clone https://github.com/desihub/desiexample.git
+    cd desiexample
+    desi_api_file desiexample
+
+:command:`desi_api_file` will refuse to overwrite an existing file, unless the
+``--overwrite`` option is supplied.  The ``--overwrite`` option is a good way
+to ensure that your API documentation is in sync with the actual Python files
+in the software product.
+
+Note: this command *replaces* the capability::
+
+    python setup.py api
+
+that was provided in earlier versions of desiutil.
+
+Module File Generation
+----------------------
+
+:command:`desi_module_file` creates a `Module file`_ for a DESI software product.
+It is meant to be run in the working directory or git clone of a software product.
+
+Normally this step is automatically performed by :doc:`desiInstall <./desiInstall>`, but
+this script is provided to create Module files independently of :command:`desiInstall`.
+
+Example::
+
+    git clone https://github.com/desihub/desispec.git
+    cd desispec
+    desi_module_file -m /separate/module/directory/modulefiles desispec main
+
+.. _`Module file`: https://docs.nersc.gov/environment/modules/
+
+Note: this command *replaces* the capability::
+
+    python setup.py module_file
+
+that was provided in earlier versions of desiutil.
+
+Version String Update
+---------------------
+
+:command:`desi_update_version` creates or updates ``py/packagename/_version.py``.
+In most DESI packages, this file is then used to create ``__version__``
+in the top-level ``__init__.py`` file::
+
+    from ._version import __version__
+
+To create or update a ``_version.py`` file for a git clone::
+
+    git clone https://github.com/desihub/desispec.git
+    cd desispec
+    desi_update_version desispec
+
+The actual version string is based on the last known tag and the number of
+git commits.
+
+In preparation for a tag, the version string should be set explicitly::
+
+    desi_update_version --tag 1.2.3 desispec
+    git tag 1.2.3
+
+Note: this command *replaces* the capability::
+
+    python setup.py version
+
+that was provided in earlier versions of desiutil.
+
+Update IERS Data
+----------------
+
+:command:`update_iers_frozen` is an internal utility command that updates
+data files stored in the desiutil package that are used with :mod:`desiutil.iers`.
+See that module for further details.
+
+Shell Scripts
+=============
+
+Bootstrap DESI Environment
+--------------------------
+
+:command:`desiBootstrap.sh` is used to set up a bare-bones DESI software
+environment, for example, for an entirely new system at NERSC.  It downloads
+and sets up a version of desiutil, which it then uses to :command:`desiInstall`
+an "official" version of desiutil.  From there, that "official" version can
+be used to :command:`desiInstall` other DESI software packages.
+
+Set DESI-friendly Permissions
+-----------------------------
+
+:command:`fix_permissions.sh` recursively changes permissions in a directory
+to match DESI standards:
+
+* All files belong to group ``desi``;
+* All files are readable by group ``desi``;
+* All directories are at least readable and accessible by group ``desi``.
+
+See also the `NERSC filesystem discussion`_.
+
+Example::
+
+    fix_permissions.sh /global/cfs/cdirs/desi/users/desi
+
+.. _`NERSC filesystem discussion`: https://desi.lbl.gov/trac/wiki/Computing/NerscFileSystem#FileSystemAccess
+
+
+.. _replacing-setup-py:
+
+Replacing setup.py
+==================
+
+Introduction
+------------
+
+The Python community is gradually moving away from using ``setup.py`` for
+package build and install tasks.  In previous versions, this package provided
+plug-in commands for ``setup.py``.  The sections below give specific instructions
+for replacements for these commands, as well as test and documentation
+commands that were built-in to earlier versions of ``setup.py``.
+
+.. _setup-py-api:
+
+python setup.py api
+-------------------
+
+Use the :command:`desi_api_file` script described above to generate ``api.rst`` files.
+This command is provided by this package.
+
+.. _setup-py-build_docs:
+
+python setup.py build_docs
+--------------------------
+
+Package documentation should be built with :command:`sphinx-build`.  For example::
+
+    sphinx-build -W --keep-going -b html doc doc/_build/html
+
+If you don't already have Sphinx installed, you can install it with::
+
+    pip install Sphinx
+
+.. _setup-py-build_sphinx:
+
+python setup.py build_sphinx
+----------------------------
+
+See :ref:`build_docs <setup-py-build_docs>` above.
+
+.. _setup-py-module_file:
+
+python setup.py module_file
+---------------------------
+
+Use the :command:`desi_module_file` script described above to generate Module files.
+Note that the preferred method is to just let :command:`desiInstall` do that.
+Both commands are provided by this package.
+
+.. _setup-py-test:
+
+python setup.py test
+--------------------
+
+Use :command:`pytest` to run tests.  If you don't already have :command:`pytest`
+installed, you can install it with::
+
+    pip install pytest
+
+.. _setup-py-version:
+
+python setup.py version
+-----------------------
+
+Use the :command:`desi_update_version` script described above to update the version
+string in a package. This command is provided by this package.