Add developer requirements to setup.py (#712)

* Remove env_developer.yml in favor of setup.py extras

* Remove `requirements/env_developer.yml`.
* Add extras for docs and test to `setup.py`.
* Fix requirements:
  - Remove descartes, it was not used.
  - Remove pandoc in favor of myst_nb.

* Add instructions for installing extras

* Install extra requirements in readthedocs pipeline

* Fix typo in .readthedocs

* Add myst-nb settings to doc/conf.py

* Use colon instead of underscore in setup.py dep specs

* Update CHANGELOG.md

* Fix header slugs in doc/guide/Guide_CLIMADA_Tutorial.ipynb

* installation guide: use double quotes for compatibility with Windows

---------

Co-authored-by: emanuel-schmid <[email protected]>

Author: peanutfun

.readthedocs.yml

@@ -8,5 +8,12 @@ build:
 conda:
   environment: requirements/env_docs.yml
 
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - doc
+
 formats:
   - pdf

CHANGELOG.md

@@ -13,12 +13,15 @@ Added:
 Changed:
 
 Removed:
+- `nbsphinx` [#712](https://github.com/CLIMADA-project/climada_python/pull/712)
+- `pandoc` [#712](https://github.com/CLIMADA-project/climada_python/pull/712)
 
 ### Added
 
 - `Impact.impact_at_reg` method for aggregating impacts per country or custom region [#642](https://github.com/CLIMADA-project/climada_python/pull/642)
 - `Impact.match_centroids` convenience method for matching (hazard) centroids to impact objects [#602](https://github.com/CLIMADA-project/climada_python/pull/602)
 - `climada.util.coordinates.match_centroids` method for matching (hazard) centroids to GeoDataFrames [#602](https://github.com/CLIMADA-project/climada_python/pull/602)
+- 'Extra' requirements `doc`, `test`, and `dev` for Python package [#712](https://github.com/CLIMADA-project/climada_python/pull/712)
 
 ### Changed
 
@@ -31,6 +34,7 @@ Removed:
 - The sigmoid and step impact functions now require the user to define the hazard type. [#675](https://github.com/CLIMADA-project/climada_python/pull/675)
 - Improved error messages produced by `ImpactCalc.impact()` in case hazard type is not found in exposures/impf_set [#691](https://github.com/CLIMADA-project/climada_python/pull/691)
 - Tests with long runtime were moved to integration tests in `climada/test` [#709](https://github.com/CLIMADA-project/climada_python/pull/709)
+- Use `myst-nb` for parsing Jupyter Notebooks for the documentation instead of `nbsphinx` [#712](https://github.com/CLIMADA-project/climada_python/pull/712)
 
 ### Fixed
 
@@ -40,6 +44,8 @@ Removed:
 
 ### Removed
 
+- `requirements/env_developer.yml` environment specs. Use 'extra' requirements when installing the Python package instead [#712](https://github.com/CLIMADA-project/climada_python/pull/712)
+
 ## v3.3.2
 
 Release date: 2023-03-02

doc/conf.py

@@ -38,13 +38,10 @@
               'sphinx.ext.viewcode',
               'sphinx.ext.napoleon',
               'sphinx.ext.ifconfig',
-              'nbsphinx',
-              'myst_parser',
+              'myst_nb',
               'sphinx_markdown_tables',
               'readthedocs_ext.readthedocs',]
 
-nbsphinx_allow_errors = True
-
 # read the docs version used for links
 if 'dev' in __version__:
     read_docs_url = 'en/latest/'
@@ -54,12 +51,6 @@
 # Add any paths that contain templates here, relative to this directory.
 templates_path = []
 
-# The suffix of source filenames.
-source_suffix = {
-    ".rst": "restructuredtext",
-    ".md": "markdown",
-}
-
 # The encoding of source files.
 #source_encoding = 'utf-8'
 
@@ -247,6 +238,28 @@ def remove_module_docstring(app, what, name, obj, options, lines):
 
 autodoc_member_order = "bysource"
 
+# --- MYST Parser settings ----
+
+# Jupyter Notebooks will not be executed when creating the docs
+nb_execution_mode = "off"
+
+# Extensions, see https://myst-parser.readthedocs.io/en/latest/configuration.html#list-of-syntax-extensions
+myst_enable_extensions = [
+    "amsmath",
+    "colon_fence",
+    "deflist",
+    "dollarmath",
+    "html_image",
+]
+
+# URI schemes that are converted to external links
+myst_url_schemes = ("http", "https", "mailto")
+
+# Generate heading anchors for linking to them, up to heading level 4
+myst_heading_anchors = 4
+
+# ---
+
 def setup(app):
     app.connect("autodoc-skip-member", skip)
     app.connect("autodoc-process-docstring", remove_module_docstring)

doc/guide/Guide_CLIMADA_Tutorial.ipynb

@@ -15,10 +15,10 @@
     "\n",
     "## Content\n",
     "\n",
-    "- [Why tutorials](#Why-tutorials)\n",
-    "- [Basic structure](#Basic-structure)\n",
-    "- [Good examples](#Good-examples)\n",
-    "- [Use only Markdown for headers and table of content](#Use-only-Markdown-for-headers-and-table-of-content)"
+    "- [Why tutorials](#why-tutorials)\n",
+    "- [Basic structure](#basic-structure)\n",
+    "- [Good examples](#good-examples)\n",
+    "- [Use only Markdown for headers and table of content](#use-only-markdown-for-headers-and-table-of-content)"
    ]
   },
   {

doc/guide/install.rst

@@ -169,6 +169,35 @@ For advanced Python users or developers of CLIMADA, we recommed cloning the CLIM
    If this test passes, great!
    You are good to go.
 
+Install Developer Dependencies (Optional)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Building the documentation and running the entire test suite of CLIMADA requires additional dependencies which are not installed by default.
+They are also not needed for using CLIMADA.
+However, if you want to develop CLIMADA, we recommend you install them.
+
+With the ``climada_env`` activated, enter the workspace directory and then the CLIMADA repository as above.
+Then, add the ``dev`` extra specification to the ``pip install`` command (**mind the quotation marks**, and see also `pip install examples <https://pip.pypa.io/en/stable/cli/pip_install/#examples>`_):
+
+.. code-block:: shell
+
+   python -m pip install -e "./[dev]"
+
+The CLIMADA Python package defines the following `extras <https://peps.python.org/pep-0508/#extras>`_:
+
+.. list-table::
+   :header-rows: 1
+   :widths: 1 5
+
+   * - Extra
+     - Includes Dependencies...
+   * - ``doc``
+     - for building documentation
+   * - ``test``
+     - for running and evaluating tests
+   * - ``dev``
+     - combination of ``doc`` and ``test``
+
 Install CLIMADA Petals (Optional)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 

requirements/env_climada.yml

@@ -41,7 +41,3 @@ dependencies:
   - xarray>=2023.3
   - xlrd>=2.0
   - xlsxwriter>=3.0
-  - pip:
-    - deprecation>=2.1
-    - overpy>=0.6
-    - peewee>=3.16

requirements/env_developer.yml

@@ -10,6 +10,24 @@
 with open(here.joinpath('README.md'), encoding='utf-8') as f:
     long_description = f.read()
 
+# Requirements for documentation
+DEPS_DOC = [
+    "ipython",
+    "myst-nb",
+    "readthedocs-sphinx-ext>=2.2",
+    "sphinx",
+    "sphinx-book-theme",
+    "sphinx-markdown-tables",
+]
+
+# Requirements for testing
+DEPS_TEST = [
+    "coverage>=7.2",
+    "ipython",
+    "mccabe>=0.6",
+    "pylint==2.7.1",
+]
+
 setup(
     name='climada',
 
@@ -78,5 +96,11 @@
         'xmlrunner'
     ],
 
+    extras_require={
+        "doc": DEPS_DOC,
+        "test": DEPS_TEST,
+        "dev": DEPS_DOC + DEPS_TEST
+    },
+
     include_package_data=True
 )