switch docs theme to alabaster, rework index and data model pages (#…

…277)

* switch to Sphinx standard theme (recommended by RTD)

* set sidebars with GitHub button and use theme for logo settings

* add description in sidebar

* automatically bump copyright year going forward

* restructure pyam overview on index page

* move 'contributing' to own page

* set toc-max-depth to 2 on index page and in sidebar

* edit and consistent hierarchy formatting for install-page

* use `sphinxcontrib-fulltoc` instead of overriding `navigation.html`

* shorter section title on install-page

* move bib-file to own folder

* add reference to JOSS paper on index page, move `| br|` to `conf.py`

* switch to `|pyam|` rst-prolog for consistency

* reworking the `data model` page

* add `jpg` to .gitignore

* clean-up of `conf.py`

* add new dependency `sphinxcontrib-fulltoc`

* add to readme

.gitignore

@@ -4,6 +4,7 @@
 *csv
 *xlsx
 *png
+*jpg
 *pdf
 
 # Apple file system

CONTRIBUTING.rst

@@ -12,8 +12,8 @@ Have a question? Get in touch!
 .. _Slack: https://slack.com
 
 
-Interested in Contributing? Welcome to the team!
-------------------------------------------------
+Interested in contributing? Join to the team!
+---------------------------------------------
 
 The pyam package has been developed with the explicit aim to facilitate
 open and collaborative analysis of integrated assessment and climate models.

RELEASE_NOTES.md

@@ -1,6 +1,7 @@
 
 # Next Release
 
+- [#277](https://github.com/IAMconsortium/pyam/pull/277) Restructure and extend the docs pages, switch to RTD-supported theme
 - [#275](https://github.com/IAMconsortium/pyam/pull/275) Completely removes all features related to region plotting, notably `region_plot()` and `read_shapefile()`
 - [#270](https://github.com/IAMconsortium/pyam/pull/270) Include variables with zeros in `stack_plot`  (see [#266](https://github.com/IAMconsortium/pyam/issues/266))
 - [#269](https://github.com/IAMconsortium/pyam/pull/269) Ensure append doesn't accidentally swap indexes

doc/environment.yml

@@ -15,5 +15,5 @@ dependencies:
     - pillow==5.4.1
     - sphinxcontrib-bibtex
     - sphinxcontrib-programoutput
+    - sphinxcontrib-fulltoc
     - nbsphinx
-

doc/source/_bib/data.bib

@@ -0,0 +1,12 @@
+@misc{Huppmann:2019:scenario-data,
+  author = {Huppmann, Daniel and Kriegler, Elmar and Krey, Volker and
+    Riahi, Keywan and Rogelj, Joeri and Calvin, Katherine and
+    Humpenoeder, Florian and Popp, Alexander and Rose, Steven K. and
+    Weyant, John and et al.},
+  doi = {10.5281/zenodo.3363345},
+  howpublished = {Integrated Assessment Modeling Consortium & International Institute for Applied Systems Analysis},
+  publisher = {Integrated Assessment Modeling Consortium & International Institute for Applied Systems Analysis},
+  title = {{IAMC 1.5 °C Scenario Explorer and Data hosted by IIASA (release 2.0)}},
+  url = {https://data.ene.iiasa.ac.at/iamc-1.5c-explorer},
+  year = {2019}
+}

doc/source/_bib/index.bib

@@ -0,0 +1,11 @@
+@article{Gidden:2019:pyam,
+  author = {Gidden, Matthew and Huppmann, Daniel},
+  title = {{pyam: a Python package for the analysis and visualization of models
+  of the interaction of climate, human, and environmental Systems}},
+  journal = {Journal of Open Source Software (JOSS)},
+  volume = {4},
+  number = {33},
+  pages = {1095},
+  year = {2019},
+  doi = {10.21105/joss.01095},
+}

doc/source/refs.bib → doc/source/_bib/install.bib

@@ -1,4 +1,3 @@
-
 @Misc{numpy,
 author =    {Travis Oliphant},
 title =     {{NumPy}: A guide to {NumPy}},