diff --git a/.cruft.json b/.cruft.json index f67b403f..3b9aa30b 100644 --- a/.cruft.json +++ b/.cruft.json @@ -11,7 +11,7 @@ "project_slug": "xscen", "project_short_description": "A climate change scenario-building analysis framework, built with xclim/xarray.", "pypi_username": "RondeauG", - "version": "0.7.5-beta", + "version": "0.7.6-beta", "use_pytest": "y", "use_black": "y", "add_pyup_badge": "n", diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 2dfe235a..acd296d9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -3,7 +3,7 @@ default_language_version: repos: - repo: https://github.com/asottile/pyupgrade - rev: v3.10.1 + rev: v3.11.0 hooks: - id: pyupgrade args: [ '--py39-plus' ] diff --git a/.readthedocs.yml b/.readthedocs.yml index 4b04e1fb..4192147e 100644 --- a/.readthedocs.yml +++ b/.readthedocs.yml @@ -17,6 +17,8 @@ build: pre_build: - sphinx-apidoc -o docs/apidoc --private --module-first xscen - env SKIP_NOTEBOOKS=1 sphinx-build -b linkcheck docs/ _build/linkcheck +# post_build: +# - rm -rf docs/notebooks/_data conda: environment: environment-dev.yml diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 5a67da34..170e53d7 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -111,6 +111,12 @@ Ready to contribute? Here's how to set up `xscen` for local development. $ cd docs/ $ make html +.. note:: + + When building the documentation, the default behaviour is to evaluate notebooks ('nbsphinx_execute = "always"'), rather than simply parse the content ('nbsphinx_execute = "never"'). Due to their complexity, this can sometimes be a very computationally demanding task and should only be performed when necessary (i.e.: when the notebooks have been modified). + + In order to speed up documentation builds, setting a value for the environment variable "SKIP_NOTEBOOKS" (e.g. "$ export SKIP_NOTEBOOKS=1") will prevent the notebooks from being evaluated on all subsequent "$ tox -e docs" or "$ make docs" invocations. + 8. Submit a pull request through the GitHub website. Pull Request Guidelines diff --git a/HISTORY.rst b/HISTORY.rst index eca7e980..fb1044e3 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -22,6 +22,7 @@ Breaking changes Bug fixes ^^^^^^^^^ * Fixed a bug in ``xs.search_data_catalogs`` when searching for fixed fields and specific experiments/members. (:pull:`251`). +* Fixed a bug in the documentation build configuration that prevented stable/latest and tagged documentation builds from resolving on ReadTheDocs. (:pull:`256`). Internal changes ^^^^^^^^^^^^^^^^ diff --git a/docs/conf.py b/docs/conf.py index c0eeccfd..d6ad8631 100755 --- a/docs/conf.py +++ b/docs/conf.py @@ -21,14 +21,15 @@ import os import sys import warnings +from datetime import datetime from pathlib import Path -sys.path.insert(0, os.path.abspath('..')) -if os.environ.get('READTHEDOCS') and 'ESMFMKFILE' not in os.environ: +sys.path.insert(0, os.path.abspath("..")) +if os.environ.get("READTHEDOCS") and "ESMFMKFILE" not in os.environ: # RTD doesn't activate the env, and esmpy depends on a env var set there # We assume the `os` package is in {ENV}/lib/pythonX.X/os.py # See conda-forge/esmf-feedstock#91 and readthedocs/readthedocs.org#4067 - os.environ['ESMFMKFILE'] = str(Path(os.__file__).parent.parent / 'esmf.mk') + os.environ["ESMFMKFILE"] = str(Path(os.__file__).parent.parent / "esmf.mk") import xscen # noqa import xarray # noqa @@ -53,7 +54,7 @@ "sphinx.ext.viewcode", "nbsphinx", "sphinx_codeautolink", - "sphinx_copybutton" + "sphinx_copybutton", ] # To ensure that underlined fields (e.g. `_field`) are shown in the docs. @@ -68,25 +69,29 @@ autosectionlabel_maxdepth = 2 autosummary_generate = True -nbsphinx_execute = "always" -# To avoid running notebooks on linkcheck +nbsphinx_execute = "always" +# To avoid running notebooks on linkcheck and when building PDF. try: skip_notebooks = int(os.getenv("SKIP_NOTEBOOKS")) except TypeError: skip_notebooks = False if skip_notebooks: - warnings.warn("Not executing notebooks.") + warnings.warn("SKIP_NOTEBOOKS is set. Not executing notebooks.") nbsphinx_execute = "never" +elif (os.getenv("READTHEDOCS_VERSION_NAME") in ["latest", "stable"]) or ( + os.getenv("READTHEDOCS_VERSION_TYPE") in ["tag"] +): + if Path(__file__).parent.joinpath("notebooks/_data").exists(): + warnings.warn("Notebook artefacts found. Not executing notebooks.") + nbsphinx_execute = "never" # if skip_notebooks or os.getenv("READTHEDOCS_VERSION_TYPE") in [ # "branch", # "external", # ]: -# elif os.getenv("READTHEDOCS_VERSION_NAME") in ["latest", "stable"]: -# nbsphinx_execute = "always" -# else: -# nbsphinx_execute = "auto" +# warnings.warn("Not executing notebooks.") +# nbsphinx_execute = "never" # To avoid having to install these and burst memory limit on ReadTheDocs. # autodoc_mock_imports = [ @@ -136,14 +141,14 @@ # You can specify multiple suffix as a list of string: # # source_suffix = ['.rst', '.md'] -source_suffix = ['.rst'] +source_suffix = [".rst"] # The master toctree document. -master_doc = 'index' +master_doc = "index" # General information about the project. -project = 'xscen' -copyright = "2022, Ouranos Inc., Gabriel Rondeau-Genesse, and contributors" +project = "xscen" +copyright = f"2022-{datetime.now().year}, Ouranos Inc., Gabriel Rondeau-Genesse, and contributors" author = "Gabriel Rondeau-Genesse" # The version info for the project you're documenting, acts as replacement @@ -172,7 +177,7 @@ ] # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = "sphinx" # If true, `todo` and `todoList` produce output, else they produce nothing. todo_include_todos = False @@ -201,13 +206,13 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = ['_static'] +html_static_path = ["_static"] # -- Options for HTMLHelp output --------------------------------------- # Output file base name for HTML help builder. -htmlhelp_basename = 'xscendoc' +htmlhelp_basename = "xscendoc" # -- Options for LaTeX output ------------------------------------------ @@ -216,15 +221,12 @@ # The paper size ('letterpaper' or 'a4paper'). # # 'papersize': 'letterpaper', - # The font size ('10pt', '11pt' or '12pt'). # # 'pointsize': '10pt', - # Additional stuff for the LaTeX preamble. # # 'preamble': '', - # Latex figure (float) alignment # # 'figure_align': 'htbp', @@ -234,9 +236,13 @@ # (source start file, target name, title, author, documentclass # [howto, manual, or own class]). latex_documents = [ - (master_doc, 'xscen.tex', - 'xscen Documentation', - 'Gabriel Rondeau-Genesse', 'manual'), + ( + master_doc, + "xscen.tex", + "xscen Documentation", + "Gabriel Rondeau-Genesse", + "manual", + ), ] @@ -244,11 +250,7 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). -man_pages = [ - (master_doc, 'xscen', - 'xscen Documentation', - [author], 1) -] +man_pages = [(master_doc, "xscen", "xscen Documentation", [author], 1)] # -- Options for Texinfo output ---------------------------------------- @@ -257,10 +259,13 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'xscen', - 'xscen Documentation', - author, - 'xscen', - 'One line description of project.', - 'Miscellaneous'), + ( + master_doc, + "xscen", + "xscen Documentation", + author, + "xscen", + "One line description of project.", + "Miscellaneous", + ), ] diff --git a/setup.cfg b/setup.cfg index 004df997..153fd468 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,5 +1,5 @@ [bumpversion] -current_version = 0.7.5-beta +current_version = 0.7.6-beta commit = True tag = False parse = (?P\d+)\.(?P\d+).(?P\d+)(\-(?P[a-z]+))? diff --git a/setup.py b/setup.py index 3d49e3ca..be2432fb 100644 --- a/setup.py +++ b/setup.py @@ -80,6 +80,6 @@ test_suite="tests", extras_require={"dev": dev_requirements}, url="https://github.com/Ouranosinc/xscen", - version="0.7.5-beta", + version="0.7.6-beta", zip_safe=False, ) diff --git a/tests/test_xscen.py b/tests/test_xscen.py index 5bbcbc69..f680f1eb 100644 --- a/tests/test_xscen.py +++ b/tests/test_xscen.py @@ -28,4 +28,4 @@ def test_package_metadata(self): contents = f.read() assert """Gabriel Rondeau-Genesse""" in contents assert '__email__ = "rondeau-genesse.gabriel@ouranos.ca"' in contents - assert '__version__ = "0.7.5-beta"' in contents + assert '__version__ = "0.7.6-beta"' in contents diff --git a/xscen/__init__.py b/xscen/__init__.py index 7e61e09c..16fadd97 100644 --- a/xscen/__init__.py +++ b/xscen/__init__.py @@ -52,7 +52,7 @@ __author__ = """Gabriel Rondeau-Genesse""" __email__ = "rondeau-genesse.gabriel@ouranos.ca" -__version__ = "0.7.5-beta" +__version__ = "0.7.6-beta" # monkeypatch so that warnings.warn() doesn't mention itself