Commit c1580382 authored by Paul McCarthy's avatar Paul McCarthy 🚵
Browse files

Merge branch 'mnt/fsl-package' into 'master'

Mnt/fsl package

See merge request fsl/fslpy!290
parents 60f6e154 d209520e
...@@ -4,4 +4,5 @@ set -e ...@@ -4,4 +4,5 @@ set -e
pip install -r requirements-dev.txt pip install -r requirements-dev.txt
python setup.py doc python setup.py doc
mv doc/html doc/"$CI_COMMIT_REF_NAME" mkdir -p public
mv doc/html/* public/
#!/usr/bin/env bash
set -e
rsync -rv doc/"$CI_COMMIT_REF_NAME" "docdeploy:"
...@@ -9,12 +9,12 @@ ...@@ -9,12 +9,12 @@
# #
# 2. style: Check coding style # 2. style: Check coding style
# #
# 3. doc: Building API documentation # 3. doc: Building and upload API documentation using GitLab Pages.
# #
# 4. build: Building source and wheel distributions # 4. build: Building source and wheel distributions
# #
# 5. deploy: Uploading the build outputs to pypi/hosting servers, and the # 5. deploy: Uploading the build outputs to pypi/hosting servers.
# documentation to a hosting server. #
# #
# Custom docker images are used for several jobs - these images are # Custom docker images are used for several jobs - these images are
# available at: # available at:
...@@ -24,13 +24,10 @@ ...@@ -24,13 +24,10 @@
# The test and style stages are executed on all branches of upstream and fork # The test and style stages are executed on all branches of upstream and fork
# repositories. # repositories.
# #
# The doc stage, and the deploy-doc job, is executed on all branches of the # The doc stage is executed on release branches of the upstream repository.
# upstream repository.
#
# The build stage, and the remaining jobs in the deploy stage, are only
# executed on the upstream repository, and only for release tags.
# #
# The deploy stages are manually instantiated. # The build and deploy stages are executed on tags on the upstream
# repository, and the deploy stage must be manually instantiated.
# #
# Most of the logic for each job is defined in shell scripts in the .ci # Most of the logic for each job is defined in shell scripts in the .ci
# sub-directory. # sub-directory.
...@@ -61,16 +58,10 @@ stages: ...@@ -61,16 +58,10 @@ stages:
# - SSH_PRIVATE_KEY_FSL_DOWNLOAD - private key for downloading some FSL # - SSH_PRIVATE_KEY_FSL_DOWNLOAD - private key for downloading some FSL
# files from a remote server (FSL_HOST) # files from a remote server (FSL_HOST)
# #
# - SSH_PRIVATE_KEY_DOC_DEPLOY - private key for rsyncing documentation
# to remote host (DOC_HOST)
#
# - SSH_SERVER_HOSTKEYS - List of trusted SSH hosts # - SSH_SERVER_HOSTKEYS - List of trusted SSH hosts
# #
# - DOC_HOST: - Username@host to upload documentation to
# (e.g. "paulmc@jalapeno.fmrib.ox.ac.uk")
#
# - FSL_HOST: - Username@host to download FSL data from # - FSL_HOST: - Username@host to download FSL data from
# (e.g. "paulmc@jalapeno.fmrib.ox.ac.uk") # (most likely "paulmc@localhost")
# #
# - FSL_ATLAS_DIR: - Location of the FSL atlas data on # - FSL_ATLAS_DIR: - Location of the FSL atlas data on
# FSL_HOST. # FSL_HOST.
...@@ -110,6 +101,11 @@ variables: ...@@ -110,6 +101,11 @@ variables:
- master@fsl/fslpy - master@fsl/fslpy
.only_release_branches: &only_release_branches
only:
- /^v.+$/@fsl/fslpy
.only_releases: &only_releases .only_releases: &only_releases
only: only:
- tags@fsl/fslpy - tags@fsl/fslpy
...@@ -201,12 +197,18 @@ style: ...@@ -201,12 +197,18 @@ style:
TEST_STYLE: "true" TEST_STYLE: "true"
########### #############
# Doc stage # Pages stage
########### #############
# I would like to have separate doc deploys for
# both the master and latest release branches,
# but this is awkward with gitlab pages. So
# currently the most recently executed pages
# job is the one that gets deployed.
build-doc: pages:
<<: *only_upstream <<: *only_release_branches
tags: tags:
- docker - docker
...@@ -218,9 +220,8 @@ build-doc: ...@@ -218,9 +220,8 @@ build-doc:
- bash ./.ci/build_doc.sh - bash ./.ci/build_doc.sh
artifacts: artifacts:
expire_in: 1 day
paths: paths:
- doc/$CI_COMMIT_REF_NAME - public
############# #############
...@@ -252,23 +253,6 @@ build-pypi-dist: ...@@ -252,23 +253,6 @@ build-pypi-dist:
############## ##############
deploy-doc:
<<: *only_upstream
<<: *setup_ssh
stage: deploy
when: manual
image: python:3.7
tags:
- docker
dependencies:
- build-doc
script:
- bash ./.ci/deploy_doc.sh
deploy-pypi: deploy-pypi:
<<: *only_releases <<: *only_releases
<<: *setup_ssh <<: *setup_ssh
......
...@@ -10,7 +10,14 @@ order. ...@@ -10,7 +10,14 @@ order.
Changed Changed
^^^^^^^ ^^^^^^^
* The ``fslpy`` API ocumentation is now hosted at
https://open.win.ox.ac.uk/fsl/fslpy
* The :mod:`fsl` and :mod:`fsl.scripts` packages have been changed from being
`pkgutil-style
<https://packaging.python.org/guides/packaging-namespace-packages/#pkgutil-style-namespace-packages>`_
namespace packages to now being `native
<https://packaging.python.org/guides/packaging-namespace-packages/#native-namespace-packages>`_
namespace packages.
* The :class:`.TaskThread` now allows an error handler function to be * The :class:`.TaskThread` now allows an error handler function to be
specified, which is run on the :mod:`.idle` loop. specified, which is run on the :mod:`.idle` loop.
* The :func:`.bids.loadMetadata` function no long resolves sym-links when * The :func:`.bids.loadMetadata` function no long resolves sym-links when
......
``fsl``
=======
.. toctree::
:hidden:
fsl.data
fsl.scripts
fsl.utils
fsl.transform
fsl.version
fsl.wrappers
.. automodule:: fsl
:members:
:undoc-members:
:show-inheritance:
...@@ -20,7 +20,11 @@ ...@@ -20,7 +20,11 @@
fsl.scripts.Text2Vest fsl.scripts.Text2Vest
fsl.scripts.Vest2Text fsl.scripts.Vest2Text
.. automodule:: fsl.scripts
:members: The ``fsl.scripts`` package contains all of the executable scripts provided by
:undoc-members: ``fslpy``, and other python-based FSL packages.
:show-inheritance:
The ``fsl.scripts`` package is a `native namespace package
<https://packaging.python.org/guides/packaging-namespace-packages/>`_, which
means that it can be used by other Python libraries.
...@@ -8,24 +8,53 @@ within `FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki>`_ and by ...@@ -8,24 +8,53 @@ within `FSL <https://fsl.fmrib.ox.ac.uk/fsl/fslwiki>`_ and by
|fsleyes_apidoc|_. |fsleyes_apidoc|_.
The top-level Python package for ``fslpy`` is called ``fsl``. It is broadly The top-level Python package for ``fslpy`` is called :mod:`fsl`. It is
split into the following sub-packages: broadly split into the following sub-packages:
+----------------------+-----------------------------------------------------+
| :mod:`fsl.data` | contains data abstractions and I/O routines for a |
| | range of FSL and neuroimaging file types. Most I/O |
| | routines use `nibabel <https://nipy.org/nibabel/>`_ |
| | extensively. |
+----------------------+-----------------------------------------------------+
| :mod:`fsl.utils` | contains a range of miscellaneous utilities, |
| | including :mod:`fsl.utils.path`, |
| | :mod:`fsl.utils.run`, and :mod:`fsl.utils.bids` |
+----------------------+-----------------------------------------------------+
| :mod:`fsl.scripts` | contains a range of scripts which are installed as |
| | FSL commands. |
+----------------------+-----------------------------------------------------+
| :mod:`fsl.transform` | contains functions and classes for working with |
| | FSL-style linear and non-linear transformations. |
+----------------------+-----------------------------------------------------+
| :mod:`fsl.version` | simply contains the ``fslpy`` version number. |
+----------------------+-----------------------------------------------------+
| :mod:`fsl.wrappers` | contains Python functions which can be used to |
| | invoke FSL commands. |
+----------------------+-----------------------------------------------------+
The :mod:`fsl` package provides the top-level Python package namespace for
``fslpy``, and for other FSL python libaries. It is a `native namespace
package <https://packaging.python.org/guides/packaging-namespace-packages/>`_,
which means that there is no ``fsl/__init__.py`` file.
Other libraries can use the ``fsl`` package namepace simply by also omitting a
``fsl/__init__.py`` file, and by ensuring that there are no naming conflicts
with any sub-packages of ``fslpy`` or any other projects which use the ``fsl``
package namespace.
.. autosummary::
fsl.data
fsl.utils
fsl.scripts
fsl.transform
fsl.version
fsl.wrappers
.. toctree:: .. toctree::
:hidden: :hidden:
self self
fsl fsl.data
fsl.scripts
fsl.transform
fsl.utils
fsl.wrappers
fsl.version
contributing contributing
changelog changelog
#!/usr/bin/env python
#
# __init__.py - The fslpy library.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
"""The :mod:`fsl` package is a library which contains convenience classes
and functions for use by FSL python tools. It is broadly split into the
following sub-packages:
.. autosummary::
fsl.data
fsl.utils
fsl.scripts
fsl.transform
fsl.version
fsl.wrappers
.. note:: The ``fsl`` namespace is a ``pkgutil``-style *namespace package* -
it can be used across different projects - see
https://packaging.python.org/guides/packaging-namespace-packages/
for details.
"""
__path__ = __import__('pkgutil').extend_path(__path__, __name__) # noqa
#!/usr/bin/env python
#
# __init__.py - The fsl.scripts package.
#
# Author: Paul McCarthy <pauldmccarthy@gmail.com>
#
"""The ``fsl.scripts`` package contains all of the executable scripts provided
by ``fslpy``, and other python-based FSL packages.
.. note:: The ``fsl.scripts`` namespace is a ``pkgutil``-style *namespace
package* - it can be used across different projects - see
https://packaging.python.org/guides/packaging-namespace-packages/ for
details.
"""
__path__ = __import__('pkgutil').extend_path(__path__, __name__) # noqa
...@@ -18,7 +18,8 @@ ...@@ -18,7 +18,8 @@
All of the other functions in this module should not be considered part of the All of the other functions in this module should not be considered part of the
public API. public API.
.. see:: https://bids-specification.readthedocs.io/en/stable/ See https://bids-specification.readthedocs.io/en/stable/ for more information
about BIDS.
.. note:: The `pybids <https://bids-standard.github.io/pybids/>`_ library is .. note:: The `pybids <https://bids-standard.github.io/pybids/>`_ library is
a more suitable choice if you are after a more robust and featured a more suitable choice if you are after a more robust and featured
......
...@@ -325,6 +325,7 @@ from .query import FileTreeQuery ...@@ -325,6 +325,7 @@ from .query import FileTreeQuery
import fsl.utils.deprecated as deprecated import fsl.utils.deprecated as deprecated
deprecated.warn('fsl.utils.filetree', deprecated.warn('fsl.utils.filetree',
stacklevel=2,
vin='3.6.0', vin='3.6.0',
rin='4.0.0', rin='4.0.0',
msg='The filetree package is now released as a separate ' msg='The filetree package is now released as a separate '
......
...@@ -12,7 +12,7 @@ import os.path as op ...@@ -12,7 +12,7 @@ import os.path as op
import shutil import shutil
from setuptools import setup from setuptools import setup
from setuptools import find_packages from setuptools import find_namespace_packages
from setuptools import Command from setuptools import Command
...@@ -27,7 +27,7 @@ with open(op.join(basedir, 'requirements.txt'), 'rt') as f: ...@@ -27,7 +27,7 @@ with open(op.join(basedir, 'requirements.txt'), 'rt') as f:
with open(op.join(basedir, 'requirements-extra.txt'), 'rt') as f: with open(op.join(basedir, 'requirements-extra.txt'), 'rt') as f:
extra_requires = {'extras' : [l.strip() for l in f.readlines()]} extra_requires = {'extras' : [l.strip() for l in f.readlines()]}
packages = find_packages(include=('fsl', 'fsl.*')) packages = find_namespace_packages(include=('fsl', 'fsl.*'))
# Figure out the current fslpy version, as defined in fsl/version.py. We # Figure out the current fslpy version, as defined in fsl/version.py. We
# don't want to import the fsl package, as this may cause build problems. # don't want to import the fsl package, as this may cause build problems.
......
...@@ -15,7 +15,7 @@ import contextlib ...@@ -15,7 +15,7 @@ import contextlib
import argparse import argparse
import pytest import pytest
import fsl import fsl.version as fv
from fsl.utils import fslsub, run from fsl.utils import fslsub, run
from fsl.utils.tempdir import tempdir from fsl.utils.tempdir import tempdir
...@@ -63,7 +63,7 @@ with open('{{}}.o{{}}'.format(cmd, jobid), 'w') as stdout, \ ...@@ -63,7 +63,7 @@ with open('{{}}.o{{}}'.format(cmd, jobid), 'w') as stdout, \
print(str(jobid)) print(str(jobid))
sys.exit(0) sys.exit(0)
""".format(op.dirname(fsl.__file__)).strip() """.format(op.dirname(op.join(fv.__file__, '..'))).strip()
@contextlib.contextmanager @contextlib.contextmanager
def fslsub_mockFSLDIR(): def fslsub_mockFSLDIR():
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment