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 9d4c6423..4bab7fbf 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -21,6 +21,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..dcee2304 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 os.getenv("READTHEDOCS_OUTPUT") in ["pdf"]: + warnings.warn("Generating PDF version. 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", + ), ]