From 9635610f78047e6ec6e1897c3c2767d86b1615b9 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Mon, 6 Sep 2021 22:46:54 +0200 Subject: [PATCH 1/2] wip --- docs/Makefile | 11 +++++---- docs/_templates/versioning.html | 14 ++++++++++++ docs/_templates/versions.html | 27 ++++++++++++++++++++++ docs/conf.py | 40 ++++++++++++++++++++++++--------- docs/requirements.txt | 9 ++++---- setup.cfg | 9 ++++---- 6 files changed, 85 insertions(+), 25 deletions(-) create mode 100644 docs/_templates/versioning.html create mode 100644 docs/_templates/versions.html diff --git a/docs/Makefile b/docs/Makefile index aeaf2684..2ef90be1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -55,10 +55,16 @@ clean: rm -rf api/* html: - PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html + PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(CURBRANCH) @echo @echo "Build finished. The HTML pages are in $(BUILDDIR)/html." + +versioned: + PYTHONPATH=$(PYTHONPATH) sphinx-multiversion -v . $(BUILDDIR)/html/ + @echo + @echo "Multi-version build finished. The HTML pages are in $(BUILDDIR)/html." + dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml @echo @@ -180,6 +186,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/versioning.html b/docs/_templates/versioning.html new file mode 100644 index 00000000..7cbbebb9 --- /dev/null +++ b/docs/_templates/versioning.html @@ -0,0 +1,14 @@ +{% if versions %} +

{{ _('Tags') }}

+ +

{{ _('Branches') }}

+ +{% endif %} \ No newline at end of file diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html new file mode 100644 index 00000000..476c8d19 --- /dev/null +++ b/docs/_templates/versions.html @@ -0,0 +1,27 @@ +{%- if current_version %} +
+ + Other Versions + v: {{ current_version.name }} + + +
+ {%- if versions.tags %} +
+
Tags
+ {%- for item in versions.tags %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} + {%- if versions.branches %} +
+
Branches
+ {%- for item in versions.branches %} +
{{ item.name }}
+ {%- endfor %} +
+ {%- endif %} +
+
+{%- endif %} \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index f2c0232a..c875e981 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -32,15 +32,16 @@ # -- 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 = [ @@ -60,11 +61,11 @@ # 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,7 +214,12 @@ 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"] @@ -223,4 +229,16 @@ intersphinx_mapping = {"https://docs.python.org/": None} # -- Options for versioning extension ---------------------------------------- -scv_show_banner = True +html_sidebars = {"**": ["versioning.html"]} + +smv_branch_whitelist = r"^master$" +smv_tag_whitelist = r"^\d+\.\d+\.\d+(?!rc|dev).*$" +# smv_prebuild_command = f"""\ +# sphinx-apidoc \ +# {' '.join(apidoc_extra_args)} \ +# {'-e ' * apidoc_separate_modules} \ +# -o {apidoc_output_dir} \ +# {apidoc_module_dir} \ +# {' '.join([apidoc_module_dir + '/' + p for p in apidoc_excluded_paths])} +# """ +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 = From ba5e6461fc6765169ca1f868e598b1385a564d23 Mon Sep 17 00:00:00 2001 From: Oscar Esteban Date: Wed, 8 Sep 2021 09:00:33 +0200 Subject: [PATCH 2/2] fix: new approach to multiversioned docs This PR relies on a little javascript to create the dropdown menu to select the version. The sphinxcontrib-versioning package is not anymore used, and the different versions of documentation are just accumulated on the `gh-pages` branch of the repo. Therefore, all versions are not built anymore with every build. The new approach completely decouples the generation of versions of documentation from the chooser, allowing us flexibility to change themes or completely change the structure, so long the new theme or documentation scheme is capable of interpreting the `versions.json` file at the root of `gh-pages`. --- .circleci/config.yml | 84 ++------------------------------- docs/Makefile | 10 ++-- docs/_templates/versioning.html | 14 ------ docs/_templates/versions.html | 49 +++++++++++-------- docs/conf.py | 35 +++++++------- 5 files changed, 55 insertions(+), 137 deletions(-) delete mode 100644 docs/_templates/versioning.html 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 2ef90be1..1871e315 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -55,15 +55,17 @@ clean: rm -rf api/* html: - PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html/$(CURBRANCH) + 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: - PYTHONPATH=$(PYTHONPATH) sphinx-multiversion -v . $(BUILDDIR)/html/ + mkdir -p $(BUILDDIR) + PYTHONPATH=$(PYTHONPATH) sphinx-multiversion -v . $(BUILDDIR)/ @echo - @echo "Multi-version build finished. The HTML pages are in $(BUILDDIR)/html." + @echo "Multi-version build finished. The HTML pages are in $(BUILDDIR)/." dirhtml: $(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml diff --git a/docs/_templates/versioning.html b/docs/_templates/versioning.html deleted file mode 100644 index 7cbbebb9..00000000 --- a/docs/_templates/versioning.html +++ /dev/null @@ -1,14 +0,0 @@ -{% if versions %} -

{{ _('Tags') }}

- -

{{ _('Branches') }}

- -{% endif %} \ No newline at end of file diff --git a/docs/_templates/versions.html b/docs/_templates/versions.html index 476c8d19..075befa8 100644 --- a/docs/_templates/versions.html +++ b/docs/_templates/versions.html @@ -1,27 +1,36 @@ -{%- if current_version %}
Other Versions - v: {{ current_version.name }} + v: {{ version }} -
- {%- if versions.tags %} -
-
Tags
- {%- for item in versions.tags %} -
{{ item.name }}
- {%- endfor %} -
- {%- endif %} - {%- if versions.branches %} -
-
Branches
- {%- for item in versions.branches %} -
{{ item.name }}
- {%- endfor %} -
- {%- endif %} +
+
+
-{%- endif %} \ No newline at end of file + + diff --git a/docs/conf.py b/docs/conf.py index c875e981..63448275 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -10,24 +10,22 @@ # 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 = [ @@ -56,6 +54,7 @@ "svgutils", "transforms3d", ] +autodoc_autoreload = True # Accept custom section names to be parsed for numpy-style docstrings # of parameters. @@ -226,19 +225,19 @@ # -- 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 ---------------------------------------- -html_sidebars = {"**": ["versioning.html"]} - smv_branch_whitelist = r"^master$" smv_tag_whitelist = r"^\d+\.\d+\.\d+(?!rc|dev).*$" -# smv_prebuild_command = f"""\ -# sphinx-apidoc \ -# {' '.join(apidoc_extra_args)} \ -# {'-e ' * apidoc_separate_modules} \ -# -o {apidoc_output_dir} \ -# {apidoc_module_dir} \ -# {' '.join([apidoc_module_dir + '/' + p for p in apidoc_excluded_paths])} -# """ +smv_released_pattern = r'^tags/.*$' smv_rebuild_tags = False