From 7ccee7333ed0e298f38f937e6dfd217de09adfb9 Mon Sep 17 00:00:00 2001 From: Stefan Appelhoff Date: Wed, 25 Mar 2020 22:00:15 +0100 Subject: [PATCH] MRG: Devdocs (#370) * update copyright * use sphinxext instead of manually .nojekyll * DOC: circleci now builds DEV docs * make use of filepath_prefix for binder * go from ~= pip syntax to >=X,> $BASH_ENV; - - - run: - name: Setup Python environment - # ... but use latest version of MNE - command: | - conda update --yes --quiet conda - conda env create -f environment.yml --name=testenv - source activate testenv - pip install -U https://api.github.com/repos/mne-tools/mne-python/zipball/master - python setup.py develop - - - run: - name: Build the documentation - command: | - source activate testenv - make build-doc - - - store_artifacts: - path: doc/_build/html/ - destination: html - - # Store the data cache - - save_cache: - key: data-cache-0-{{ checksum "./mne_bids/__init__.py" }} - paths: - - ~/mne_data - - # Store pip cache - - save_cache: - key: pip-cache-0-{{ checksum "./environment.yml" }} - paths: - - ~/.cache/pip - - - add_ssh_keys: - fingerprints: - - "bf:ac:92:1d:dc:ca:a0:2d:aa:f6:b2:b6:d5:1c:ac:74" - - - deploy: - name: github pages deployment - command: | - source activate testenv - if [ "${CIRCLE_BRANCH}" == "maint/0.3" ]; then - echo "Deploying stable docs for ${CIRCLE_BRANCH}."; - git config --global user.email "circle@mne.com"; - git config --global user.name "Circle Ci"; - cd doc; - make install; - else - echo "No deployment (build: ${CIRCLE_BRANCH})."; - fi + docs-build: + docker: + - image: circleci/python:3.7.3-stretch + steps: + - checkout + + - run: + name: Check environment.yml and doc/environment.yml syncing + # doc/environment.yml must be a perfect copy of environment.yml + # with a single line " - mne_bids>=0.X,<0.Y" added in the pip section + command: diff <(grep -v '^ - mne_bids>=0.*,<0.*$' doc/environment.yml) <(cat environment.yml) + + # restore cache from last build. Unless __init__.py has changed since then + - restore_cache: + keys: + - data-cache-0-{{ checksum "./mne_bids/__init__.py" }} + + # Also restore pip cache to speed up installations + - restore_cache: + keys: + - pip-cache-0-{{ checksum "./environment.yml" }} + + - run: + name: Install miniconda + command: | + wget -q https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh; + chmod +x ~/miniconda.sh; + ~/miniconda.sh -b -p ~/miniconda; + echo "export PATH=~/miniconda/bin:$PATH" >> $BASH_ENV; + + - run: + name: Setup Python environment + # ... but use latest version of MNE + command: | + conda update --yes --quiet conda + conda env create -f environment.yml --name=testenv + source activate testenv + pip install -U https://api.github.com/repos/mne-tools/mne-python/zipball/master + python setup.py develop + + - run: + name: Build the documentation + command: | + source activate testenv + make build-doc + + - persist_to_workspace: + root: doc/_build + paths: html + + - store_artifacts: + path: doc/_build/html/ + destination: html + + # Store the data cache + - save_cache: + key: data-cache-0-{{ checksum "./mne_bids/__init__.py" }} + paths: + - ~/mne_data + + # Store pip cache + - save_cache: + key: pip-cache-0-{{ checksum "./environment.yml" }} + paths: + - ~/.cache/pip + + docs-deploy: + # will only be run on master branch + docker: + - image: node:8.10.0 + steps: + - checkout + + - attach_workspace: + at: doc/_build + + - run: + name: Install and configure dependencies + command: | + npm install -g --silent gh-pages@2.2 + git config --global user.email "circle@mne.com" + git config --global user.name "Circle Ci" + + - add_ssh_keys: + fingerprints: + - "7f:74:00:17:2b:1a:7d:68:56:68:6b:64:b5:e0:7f:91" + + - run: + # push built docs into the `dev` directory on the `gh-pages` branch + name: Deploy docs to gh-pages branch + command: gh-pages --dotfiles --message "doc updates [skip ci]" --dist doc/_build/html --dest ./dev + +workflows: + build: + jobs: + - docs-build + - docs-deploy: + requires: + - docs-build + filters: + branches: + only: master diff --git a/README.rst b/README.rst index 68784dd92..0fbccbbe8 100644 --- a/README.rst +++ b/README.rst @@ -69,7 +69,7 @@ Documentation The documentation can be found under the following links: - for the `stable release `_ -- for the `latest (development) version `_ +- for the `latest (development) version `_ Dependencies ------------ diff --git a/doc/Makefile b/doc/Makefile index 74ab7b6c1..d97655501 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -130,23 +130,3 @@ coverage: $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage @echo "Testing of coverage in the sources finished, look at the " \ "results in $(BUILDDIR)/coverage/python.txt." - -install: - rm -rf _build/doctrees _build/mne_bids.github.io - # first clone the mne-tools/mne_bids.github.io repo because it may ask - # for password and we don't want to delay this long build in - # the middle of it - # --no-checkout just fetches the root folder without content - # --depth 1 is a speed optimization since we don't need the - # history prior to the last commit - # -b gh-pages fetches only the branch for the gh-pages - git clone -b gh-pages --single-branch --no-checkout --depth 1 https://github.com/mne-tools/mne-bids _build/mne_bids.github.io - touch _build/mne_bids.github.io/.nojekyll - make html - cd _build/ && \ - cp -r html/* mne_bids.github.io && \ - cd mne_bids.github.io && \ - git add * && \ - git add .nojekyll && \ - git commit -a -m 'Make install' && \ - git push diff --git a/doc/_templates/navbar.html b/doc/_templates/navbar.html index 36b5868c8..e4f68b136 100644 --- a/doc/_templates/navbar.html +++ b/doc/_templates/navbar.html @@ -7,8 +7,11 @@ diff --git a/doc/conf.py b/doc/conf.py index 4c4360f9b..56c4bb418 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -28,6 +28,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.githubpages', 'sphinx.ext.autodoc', 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', @@ -54,8 +55,8 @@ # General information about the project. project = u'mne_bids' td = date.today() -copyright = u'%s, MNE Developers. Last updated on %s' % (td.year, - td.isoformat()) +copyright = u'2017-%s, MNE Developers. Last updated on %s' % (td.year, + td.isoformat()) author = u'MNE Developers' @@ -113,6 +114,16 @@ } intersphinx_timeout = 5 +# Resolve binder filepath_prefix. From the docs: +# "A prefix to append to the filepath in the Binder links. You should use this +# if you will store your built documentation in a sub-folder of a repository, +# instead of in the root." +# we will store dev docs in a `dev` subdirectory and all other docs in a +# directory "v" + version_str. E.g., "v0.3" +if 'dev' in version: + filepath_prefix = 'dev' +else: + filepath_prefix = 'v{}'.format(version) sphinx_gallery_conf = { 'examples_dirs': '../examples', @@ -126,8 +137,9 @@ 'repo': 'mne-bids', 'branch': 'gh-pages', # noqa: E501 Can be any branch, tag, or commit hash. Use a branch that hosts your docs. 'binderhub_url': 'https://mybinder.org', # noqa: E501 Any URL of a binderhub deployment. Must be full URL (e.g. https://mybinder.org). + 'filepath_prefix': filepath_prefix, # noqa: E501 A prefix to prepend to any filepaths in Binder links. 'dependencies': [ - './environment.yml' + './environment.yml', ], } } diff --git a/doc/environment.yml b/doc/environment.yml index adbe21e6a..990125a76 100644 --- a/doc/environment.yml +++ b/doc/environment.yml @@ -11,7 +11,7 @@ dependencies: - scikit-learn - matplotlib - pip: - - mne_bids~=0.3 + - mne_bids>=0.3,<0.4 - mne>=0.19.1 - nibabel - pybv diff --git a/doc/whats_new.rst b/doc/whats_new.rst index 0681b72d6..746298c01 100644 --- a/doc/whats_new.rst +++ b/doc/whats_new.rst @@ -22,7 +22,6 @@ Current Changelog ~~~~~~~~~ -- Added handedness to participant files, by `Dominik Welke`_ (`#354 `_) - Added automatic conversion of FIF to BrainVision format with warning for EEG only data and conversion to FIF for meg non-FIF data, by `Alex Rockhill`_ (`#237 `_) - Add possibility to pass raw readers parameters (e.g. `allow_maxshield`) to :func:`read_raw_bids` to allow reading BIDS-formatted data before applying maxfilter, by `Sophie Herbst`_ - New feature in :func`mne_bids.write.write_anat` for shear deface of mri, by `Alex Rockhill`_ (`#271 `_) @@ -35,7 +34,9 @@ Changelog - Update scans.tsv writer to adhere to MNE-Python v0.20+ where `meas_date` is stored as a `datetime` object, by `Adam Li`_ (`#344 `_) - :func:`read_raw_bids` now reads in sidecar json files to set, or estimate Power Line Frequency, by `Adam Li`_ (`#341 `_) - Allow FIF files with multiple parts to be read using :func:`read_raw_bids`, by `Teon Brooks`_ (`#346 `) +- Added handedness to participant files, by `Dominik Welke`_ (`#354 `_) - MNE-BIDS can now handle a paths that are `pathlib.Path` objects (in addition to strings), by `Richard Höchenberger`_ (`#362 `) +- The documentation is now available for all MNE-BIDS versions via a dropdown menu, by `Stefan Appelhoff`_(`#370 `) Bug ~~~