diff --git a/.circleci/config.yml b/.circleci/config.yml index f5aeb916..23d5855b 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,26 +1,3 @@ -docs_deploy: &docs - docker: - - image: node:8.10.0 - steps: - - checkout - - attach_workspace: - at: docs/_build - - run: - name: Disable jekyll builds - command: touch docs/_build/html/.nojekyll - - run: - name: Install and configure dependencies - command: | - npm install -g --silent gh-pages@2.0.1 - git config user.email "crn.poldracklab@gmail.com" - git config user.name "ci-build" - - add_ssh_keys: - fingerprints: - - "ae:95:0c:cc:09:84:64:99:92:82:b7:b5:f4:a7:e9:23" - - run: - name: Deploy docs to gh-pages branch - command: gh-pages --dotfiles --message "doc(update) [skip ci]" --dist docs/_build/html - version: 2 jobs: tests: @@ -149,14 +126,6 @@ jobs: - FSLOUTPUTTYPE: NIFTI - SUBJECTS_DIR: /tmp/subjects steps: - - restore_cache: - keys: - - docs-v1-{{ .Branch }}-{{ .Revision }} - - docs-v1-{{ .Branch }}- - - docs-v1-master - - docs-v1- - paths: - - ./docs/_build/_html - checkout - run: name: Create subjects folder @@ -173,30 +142,9 @@ jobs: name: Build only this commit command: | python setup.py --version - make -C docs SPHINXOPTS="-W" BUILDDIR="_build/no_version_html" html + make -C docs SPHINXOPTS="-W" BUILDDIR="/docs" CURBRANCH="${CIRCLE_TAG}" html - store_artifacts: - path: ./docs/_build/no_version_html - - run: - name: Generate Versioned Docs - command: | - set +e - force_versioned="$( git log --format=oneline -n 1 $CIRCLE_SHA1 | grep -i -E '\[docs?[ _]?versions?\]' )" - set -e - if [[ "x${CIRCLE_TAG}" = "x" && "${CIRCLE_BRANCH}" != "master" && "x${force_versioned}" = "x" ]]; then - echo "Not a tag or master branch - skipping versioned docs." - circleci step halt - else - make -f ./docs/Makefile versioned CURBRANCH=${CIRCLE_TAG:-$CIRCLE_BRANCH} - fi - - save_cache: - key: docs-v1-{{ .Branch }}-{{ .Revision }} - paths: - - ./docs/_build/_html - - persist_to_workspace: - root: docs/_build - paths: html - - store_artifacts: - path: ./docs/_build/html + path: /docs/ deploy_pypi: docker: @@ -224,12 +172,6 @@ jobs: twine check dist/* twine upload dist/* - deploy_docs_tag: - <<: *docs - - deploy_docs_master: - <<: *docs - workflows: version: 2 build_test_deploy: @@ -243,7 +185,7 @@ workflows: only: /.*/ - deploy_pypi: requires: - - deploy_docs_tag + - build_docs filters: branches: ignore: /.*/ @@ -258,26 +200,6 @@ workflows: tags: only: /.*/ - - deploy_docs_master: - requires: - - tests - - build_docs - filters: - branches: - only: /master/ - tags: - ignore: /.*/ - - - deploy_docs_tag: - requires: - - tests - - build_docs - filters: - branches: - ignore: /.*/ - tags: - only: /.*/ - nightly: triggers: - schedule: diff --git a/docs/Makefile b/docs/Makefile index aeaf2684..1871e315 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -55,9 +55,17 @@ clean: rm -rf api/* html: - PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + mkdir -p $(BUILDDIR) + PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(CURBRANCH) @echo - @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + @echo "Build finished. The HTML pages are in $(BUILDDIR)/." + + +versioned: + mkdir -p $(BUILDDIR) + PYTHONPATH=$(PYTHONPATH) sphinx-multiversion -v . $(BUILDDIR)/ + @echo + @echo "Multi-version build finished. The HTML pages are in $(BUILDDIR)/." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @@ -180,6 +188,3 @@ pseudoxml: $(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml @echo @echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml." - -versioned: - PYTHONPATH=$(PYTHONPATH) sphinx-versioning -vv -l ./docs/conf.py build -r $(CURBRANCH) ./docs/ docs/$(BUILDDIR)/html/ diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000..075befa8 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,36 @@ +
+ + Other Versions + v: {{ version }} + + +
+
+
+
+
+ + diff --git a/docs/conf.py b/docs/conf.py index f2c0232a..63448275 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,37 +10,36 @@ # add these directories to sys.path here. If the directory is relative to the # documentation root, use os.path.abspath to make it absolute, like shown here. # -import os -import sys from packaging.version import Version - from templateflow import __version__, __copyright__, __packagename__ -sys.path.append(os.path.abspath("sphinxext")) - # -- Project information ----------------------------------------------------- project = __packagename__ copyright = __copyright__ author = "The TemplateFlow Developers" -# The short X.Y version -version = Version(__version__).public # The full version, including alpha/beta/rc tags release = __version__ +# The short X.Y version +version = ( + __version__ if Version(release).public == release + else f"dev ({release.partition('+')[0]})" +) # -- General configuration --------------------------------------------------- extensions = [ "sphinx.ext.autodoc", + "sphinx.ext.coverage", "sphinx.ext.doctest", + "sphinx.ext.githubpages", + "sphinx.ext.ifconfig", "sphinx.ext.intersphinx", - "sphinx.ext.coverage", "sphinx.ext.mathjax", - "sphinx.ext.ifconfig", + "sphinx.ext.napoleon", "sphinx.ext.viewcode", - "sphinx.ext.githubpages", "sphinxcontrib.apidoc", - "sphinxcontrib.napoleon", + "sphinx_multiversion", ] autodoc_mock_imports = [ @@ -55,16 +54,17 @@ "svgutils", "transforms3d", ] +autodoc_autoreload = True # Accept custom section names to be parsed for numpy-style docstrings # of parameters. # Requires pinning sphinxcontrib-napoleon to a specific commit while # https://github.com/sphinx-contrib/napoleon/pull/10 is merged. -napoleon_use_param = False -napoleon_custom_sections = [ - ("Inputs", "Parameters"), - ("Outputs", "Parameters"), -] +# napoleon_use_param = False +# napoleon_custom_sections = [ +# ("Inputs", "Parameters"), +# ("Outputs", "Parameters"), +# ] # Add any paths that contain templates here, relative to this directory. templates_path = ["_templates"] @@ -213,14 +213,31 @@ apidoc_module_dir = "../templateflow" apidoc_output_dir = "api" -apidoc_excluded_paths = ["conftest.py", "*/tests/*", "tests/*", "data/*"] +apidoc_excluded_paths = [ + "conftest.py", + "*/tests/*", + "tests/*", + "data/*", +] apidoc_separate_modules = True apidoc_extra_args = ["--module-first", "-d 1", "-T"] # -- Options for intersphinx extension --------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. -intersphinx_mapping = {"https://docs.python.org/": None} +intersphinx_mapping = { + "bids": ("https://bids-standard.github.io/pybids/", None), + "matplotlib": ("https://matplotlib.org/", None), + "nibabel": ("https://nipy.org/nibabel/", None), + "nipype": ("https://nipype.readthedocs.io/en/latest/", None), + "numpy": ("https://numpy.org/doc/stable/", None), + "pandas": ("http://pandas.pydata.org/pandas-docs/dev", None), + "python": ("https://docs.python.org/3/", None), + "scipy": ("https://docs.scipy.org/doc/scipy/reference", None), +} # -- Options for versioning extension ---------------------------------------- -scv_show_banner = True +smv_branch_whitelist = r"^master$" +smv_tag_whitelist = r"^\d+\.\d+\.\d+(?!rc|dev).*$" +smv_released_pattern = r'^tags/.*$' +smv_rebuild_tags = False diff --git a/docs/requirements.txt b/docs/requirements.txt index 14b25b37..c534d4ea 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,3 @@ -git+https://github.com/AleksandarPetrov/napoleon.git@0dc3f28a309ad602be5f44a9049785a1026451b3#egg=sphinxcontrib-napoleon -git+https://github.com/rwblair/sphinxcontrib-versioning.git@39b40b0b84bf872fc398feff05344051bbce0f63#egg=sphinxcontrib-versioning nbsphinx packaging pybids>=0.11.1 @@ -7,7 +5,8 @@ pydot>=1.2.3 pydotplus requests sphinx-argparse -sphinx>=2.1.2 -sphinx_rtd_theme -sphinxcontrib-apidoc ~= 0.3.0 +sphinx ~= 4.0 +sphinx_rtd_theme >= 0.4.3 +sphinxcontrib-apidoc +sphinx_multiversion tqdm diff --git a/setup.cfg b/setup.cfg index 1c8d65ae..c224a2b8 100644 --- a/setup.cfg +++ b/setup.cfg @@ -61,11 +61,10 @@ doc = pydot>=1.2.3 pydotplus sphinx-argparse - sphinx>=2.1.2 - sphinx_rtd_theme - sphinxcontrib-apidoc ~= 0.3.0 - sphinxcontrib-napoleon - sphinxcontrib-versioning + sphinx ~= 4.0 + sphinx_rtd_theme >= 0.4.3 + sphinxcontrib-apidoc + sphinx_multiversion docs = %(doc)s test =