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
pip install -r requirements-dev.txt
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 @@
#
# 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
#
# 5. deploy: Uploading the build outputs to pypi/hosting servers, and the
# documentation to a hosting server.
# 5. deploy: Uploading the build outputs to pypi/hosting servers.
#
#
# Custom docker images are used for several jobs - these images are
# available at:
......@@ -24,13 +24,10 @@
# The test and style stages are executed on all branches of upstream and fork
# repositories.
#
# The doc stage, and the deploy-doc job, is executed on all branches of the
# 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 doc stage is executed on release branches of the upstream repository.
#
# 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
# sub-directory.
......@@ -61,16 +58,10 @@ stages:
# - SSH_PRIVATE_KEY_FSL_DOWNLOAD - private key for downloading some FSL
# 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
#
# - 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
# (e.g. "paulmc@jalapeno.fmrib.ox.ac.uk")
# (most likely "paulmc@localhost")
#
# - FSL_ATLAS_DIR: - Location of the FSL atlas data on
# FSL_HOST.
......@@ -110,6 +101,11 @@ variables:
- master@fsl/fslpy
.only_release_branches: &only_release_branches
only:
- /^v.+$/@fsl/fslpy
.only_releases: &only_releases
only:
- tags@fsl/fslpy
......@@ -201,12 +197,18 @@ style:
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:
<<: *only_upstream
pages:
<<: *only_release_branches
tags:
- docker
......@@ -218,9 +220,8 @@ build-doc:
- bash ./.ci/build_doc.sh
artifacts:
expire_in: 1 day
paths:
- doc/$CI_COMMIT_REF_NAME
- public
#############
......@@ -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:
<<: *only_releases
<<: *setup_ssh
......
......@@ -10,7 +10,14 @@ order.
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
specified, which is run on the :mod:`.idle` loop.
* 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 @@
fsl.scripts.Text2Vest
fsl.scripts.Vest2Text
.. automodule:: fsl.scripts
:members:
:undoc-members:
:show-inheritance:
The ``fsl.scripts`` package contains all of the executable scripts provided by
``fslpy``, and other python-based FSL packages.
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
|fsleyes_apidoc|_.
The top-level Python package for ``fslpy`` is called ``fsl``. It is broadly
split into the following sub-packages:
The top-level Python package for ``fslpy`` is called :mod:`fsl`. It is
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::
:hidden:
self
fsl
fsl.data
fsl.scripts
fsl.transform
fsl.utils
fsl.wrappers
fsl.version
contributing
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 @@
All of the other functions in this module should not be considered part of the
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
a more suitable choice if you are after a more robust and featured
......
......@@ -325,6 +325,7 @@ from .query import FileTreeQuery
import fsl.utils.deprecated as deprecated
deprecated.warn('fsl.utils.filetree',
stacklevel=2,
vin='3.6.0',
rin='4.0.0',
msg='The filetree package is now released as a separate '
......
......@@ -12,7 +12,7 @@ import os.path as op
import shutil
from setuptools import setup
from setuptools import find_packages
from setuptools import find_namespace_packages
from setuptools import Command
......@@ -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:
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
# don't want to import the fsl package, as this may cause build problems.
......
......@@ -15,7 +15,7 @@ import contextlib
import argparse
import pytest
import fsl
import fsl.version as fv
from fsl.utils import fslsub, run
from fsl.utils.tempdir import tempdir
......@@ -63,7 +63,7 @@ with open('{{}}.o{{}}'.format(cmd, jobid), 'w') as stdout, \
print(str(jobid))
sys.exit(0)
""".format(op.dirname(fsl.__file__)).strip()
""".format(op.dirname(op.join(fv.__file__, '..'))).strip()
@contextlib.contextmanager
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