Update to build docs locally (#280)

* Update to build docs locally

* Update install.rst

* fix printing requirements in `install.rst`

* add space (as suggested by @znicholls)

* set `matplotlib` requirement as a quickfix for #281

Makefile

@@ -4,6 +4,9 @@ CI_DIR=./ci
 CI_ENVIRONMENT_CONDA_DEFAULT_FILE=$(CI_DIR)/environment-conda-default.txt
 CI_ENVIRONMENT_CONDA_FORGE_FILE=$(CI_DIR)/environment-conda-forge.txt
 
+DOC_DIR=./doc
+DOC_ENVIRONMENT_CONDA_FILE=$(DOC_DIR)/environment.yml
+
 
 ifndef CONDA_PREFIX
 $(error Conda not active, please install conda and then activate it using \`conda activate\`))
@@ -93,8 +96,10 @@ $(VENV_DIR):  $(CI_ENVIRONMENT_CONDA_DEFAULT_FILE) $(CI_ENVIRONMENT_CONDA_FORGE_
 	# Install development setup
 	$(VENV_DIR)/bin/pip install -e .[tests,deploy]
 	# install docs requirements
-	cd doc; $(VENV_DIR)/bin/pip install -r requirements.txt
-	touch $(VENV_DIR)
+	# --name $(CONDA_DEFAULT_ENV) ensures we install in active environment (check at
+	# top of Makefile ensures that environment is not the base one)
+	$(CONDA_EXE) env update --name $(CONDA_DEFAULT_ENV) --file $(DOC_ENVIRONMENT_CONDA_FILE)
+# 	touch $(VENV_DIR)
 
 .PHONY: release-on-conda
 release-on-conda:  ## release pyam on conda

ci/environment-conda-forge.txt

@@ -1,5 +1,5 @@
 freetype=2.9.1
-matplotlib==3.0.3
+matplotlib==3.0.2
 matplotlib-base==3.0.3
 seaborn==0.9.0
 gdal

doc/README.md

@@ -8,11 +8,7 @@ in the source code.
 Dependencies
 ------------
 
-1. `Sphinx <http://sphinx-doc.org/>`_ v1.1.2 or higher
-2. `sphinxcontrib.bibtex`
-3. `sphinxcontrib-fulltoc`
-4. `numpydoc`
-5. `cloud_sptheme`
+These can be found in ``environment.yml``.
 
 Writing in Restructed Text
 --------------------------

doc/environment.yml

@@ -1,8 +1,8 @@
-name: pyam-docs
 channels:
   - oggm
 dependencies:
   - oggm-deps
+  - pip
   - pip:
     - ipython==7.2.0
     - matplotlib==3.0.2

doc/source/conf.py

@@ -12,6 +12,10 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+# has to go first for environment setup reasons
+import matplotlib
+matplotlib.use('agg')
+
 from datetime import datetime
 import pyam
 

doc/source/install.rst

@@ -40,11 +40,11 @@ fully enumerated below.
 
 The required depedencies for |pyam| are:
 
-  .. program-output:: python -c 'import sys; sys.path.append("../.."); import setup; print("\n".join([r for r in setup.REQUIREMENTS]))'
+  .. program-output:: python -c 'import sys; sys.path.insert(0, "../.."); from setup import REQUIREMENTS; print("\n".join([r for r in REQUIREMENTS]))'
 
 The depedencies for building this documentation are:
 
-  .. include:: ../requirements.txt
+  .. include:: ../environment.yml
 	  :start-line: 0
 	  :literal:
 

setup.py

@@ -26,7 +26,7 @@
     'PyYAML',
     'xlrd',
     'xlsxwriter',
-    'matplotlib',
+    'matplotlib<=3.0.2',
     'seaborn',
     'six',
 ]