first doc build (#1725)

docs/conf.py

@@ -127,8 +127,8 @@
     'IPython.sphinxext.ipython_console_highlighting',
 ]
 
-extlinks = {'issue': ('https://github.com/OGGM/oggm/issues/%s', 'GH'),
-            'pull': ('https://github.com/OGGM/oggm/pull/%s', 'PR'),
+extlinks = {'issue': ('https://github.com/OGGM/oggm/issues/%s', 'GH%s'),
+            'pull': ('https://github.com/OGGM/oggm/pull/%s', 'PR%s'),
             }
 
 redirects = {
@@ -336,6 +336,23 @@
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'OGGMdoc'
 
+# Read the Docs and Analytics
+# Set canonical URL from the Read the Docs Domain
+html_baseurl = os.environ.get("READTHEDOCS_CANONICAL_URL", "")
+
+# Tell Jinja2 templates the build is running on Read the Docs
+if os.environ.get("READTHEDOCS", "") == "True":
+    if "html_context" not in globals():
+        html_context = {}
+    html_context["READTHEDOCS"] = True
+
+# Plausible analytics
+html_js_files = [
+    ('https://plausible.oggm.org/js/script.js',
+     {"data-domain": "docs.oggm.org",
+      "defer": "defer"}),
+]
+
 # -- Options for LaTeX output ---------------------------------------------
 
 latex_elements = {

docs/installing-oggm-windows.rst

@@ -1,22 +1,25 @@
+.. _installing-oggm-windows:
+
 Installing OGGM on Windows
 ==========================
 
-OGGM does not work on Windows. However, there is a workaround using the Windows 
-Subsystem for Linux (WSL). There is no official support for installing OGGM on 
+OGGM does not work on Windows. However, there is a workaround using the Windows
+Subsystem for Linux (WSL). There is no official support for installing OGGM on
 Windows. Nevertheless, the steps listed hereafter have been used for a successful
 installation, but there is no guarantee that it will work for everyone.
 
 Install WSL
 -----------
+
 Enable Intel Virtual Technology
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-As a first step, you need to enable ‘Intel Virtual Technology’ to allow WSL to be 
-executed in the next step. To do this, restart your computer and access the BIOS or 
-UEFI settings by one of the following keys: F2, F12, Esc, Del. Which key you need 
-to use depends on your computer. With the arrow key you are now able to navigate to 
-the ‘configuration’ tab. Select ‘Intel Virtual Technology’ and change the settings 
-from ‘disabled’ to ‘enabled’. Save the change and exit the BIOS or UEFI settings by 
+As a first step, you need to enable ‘Intel Virtual Technology’ to allow WSL to be
+executed in the next step. To do this, restart your computer and access the BIOS or
+UEFI settings by one of the following keys: F2, F12, Esc, Del. Which key you need
+to use depends on your computer. With the arrow key you are now able to navigate to
+the ‘configuration’ tab. Select ‘Intel Virtual Technology’ and change the settings
+from ‘disabled’ to ‘enabled’. Save the change and exit the BIOS or UEFI settings by
 using F10.
 
 .. figure:: _static/windows_installation/enable_intel_virtual_technology.png
@@ -26,18 +29,19 @@ using F10.
 Enable WSL
 ~~~~~~~~~~
 
-Next you need to enable WSL. This is possible through the Windows Features dialog 
-or Power Shell. In the Windows search bar, type 'features' to bring up the 
-**Turn Windows Features on or off** dialog. Scroll down and check **Windows 
-Subsystem for Linux**. It is also necessary to tick **Virtual Machine Platform** 
-and **Windows Hypervisor Platform** to avoid errors. Click ‘OK’ and in the prompted 
+Next you need to enable WSL. This is possible through the Windows Features dialog
+or Power Shell. In the Windows search bar, type 'features' to bring up the
+**Turn Windows Features on or off** dialog. Scroll down and check **Windows
+Subsystem for Linux**. It is also necessary to tick **Virtual Machine Platform**
+and **Windows Hypervisor Platform** to avoid errors. Click ‘OK’ and in the prompted
 new field ‘install’.
 
 .. figure:: _static/windows_installation/windows_features_on_off.png
    :width: 40%
+
 |
 
-It is also possible to enable WSL as administrator via the Power Shell by using the 
+It is also possible to enable WSL as administrator via the Power Shell by using the
 following command::
 
     Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux
@@ -47,7 +51,7 @@ Afterwards you will be asked to restart Windows.
 Check WSL
 ~~~~~~~~~
 
-To be sure WSL is enabled you can check it by opening a Command Prompt and type ’WSL’ 
+To be sure WSL is enabled you can check it by opening a Command Prompt and type ’WSL’
 after restarting Windows:
 
 .. figure:: _static/windows_installation/check_wsl.png
@@ -59,12 +63,12 @@ Download Windows Subsystem for Linux and a Linux distribution of your choice
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Download the free
-`Windows subsystem for Linux <https://apps.microsoft.com/detail/windows-subsystem-for-linux/9P9TQF7MRM4R?hl=en-us&gl=US&ocid=pdpshare>`_ 
-in the Microsoft Store. With that you keep Windows as main operating system and are able 
-work with Linux alongside your Windows application. There are some limitations compared 
+`Windows subsystem for Linux <https://apps.microsoft.com/detail/windows-subsystem-for-linux/9P9TQF7MRM4R?hl=en-us&gl=US&ocid=pdpshare>`_
+in the Microsoft Store. With that you keep Windows as main operating system and are able
+work with Linux alongside your Windows application. There are some limitations compared
 to a complete second operating system, but it is sufficient to install OGGM. In addition,
 download and install `Ubuntu <https://apps.microsoft.com/detail/ubuntu/9PDXGNCFSCZV?hl=en-gb&gl=US>`_
-or another Linux distribution of your choice. 
+or another Linux distribution of your choice.
 
 UNIX User Account
 ~~~~~~~~~~~~~~~~~
@@ -77,12 +81,12 @@ Now open Ubuntu. You will automatically be asked to create a UNIX account.
 Installing OGGM
 ---------------
 
-After successfully setting up Linux as a Windows subsystem, you can proceed with the OGGM 
-installation process. There are multiple approaches available for `installing OGGM <https://docs.oggm.org/en/stable/installing-oggm.html>`_, 
-and all of them should work with WSL. However, we are aware that this may not always be 
-the case. Here, we provide an example of steps that have resulted in a successful installation. 
+After successfully setting up Linux as a Windows subsystem, you can proceed with the OGGM
+installation process. There are multiple approaches available for `installing OGGM <https://docs.oggm.org/en/stable/installing-oggm.html>`_,
+and all of them should work with WSL. However, we are aware that this may not always be
+the case. Here, we provide an example of steps that have resulted in a successful installation.
 
-1. Install the `prerequisites <https://docs.oggm.org/en/stable/installing-oggm.html#prerequisites>`_ 
+1. Install the `prerequisites <https://docs.oggm.org/en/stable/installing-oggm.html#prerequisites>`_
 for creating a python environment.
 
 2. Create a `python environment <https://docs.oggm.org/en/stable/installing-oggm.html#the-simplest-way-with-an-environment-file>`_
@@ -95,5 +99,5 @@ with ``pip install oggm``
 
 5. **Congrats**, you are now set-up for the `getting started <https://docs.oggm.org/en/stable/getting-started.html>`_ section!
 
-If you encounter problems, check out the 
+If you encounter problems, check out the
 `trouble shooting <https://docs.oggm.org/en/stable/installing-oggm.html#install-troubleshooting>`_ documentation.

docs/installing-oggm.rst

@@ -20,8 +20,14 @@ fine there as well.
     **OGGM does not work on Windows. However there is a workaround available**. If you are using Windows 10,
     we recommend to install the free
     `Windows subsystem for Linux <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_ (WSL)
-    and install and run OGGM from there. Though we don't offer support for installation, documentation 
-    of a succesfull installation can be found :ref:`here <installing-oggm-windows>`.
+    and install and run OGGM from there. Though we don't offer support for installation, documentation
+    of a succesfull installation can be found here:
+
+    .. toctree::
+        :maxdepth: 1
+
+        installing-oggm-windows.rst
+
 
 For most users we recommend to
 install Python and the package dependencies with the :ref:`conda package manager <conda-install>`,