Restructure docs and move to ReadTheDocs theme.

docs/conf.py

@@ -13,9 +13,9 @@
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = "PhysicalRisk"
-copyright = "2024, DCV"
-author = "DCV"
+project = "physrisk"
+copyright = "2024, OS-Climate"
+author = "OS-Climate"
 
 # The full version, including alpha/beta/rc tags
 # release = "1.1.0"
@@ -70,19 +70,23 @@
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_logo = "images/OS-Climate-Logo.png"
-html_theme = "pydata_sphinx_theme"
+html_theme = "sphinx_rtd_theme"
+# html_theme = "pydata_sphinx_theme"
 html_static_path = ["_static"]
 
 # Don't show the code
 html_show_sourcelink = True
 
 html_theme_options = {
-    # 'logo_only': False,
+    "logo_only": False,
     # 'display_version': False,
     # Table of contents options
     "collapse_navigation": False,
+    "style_nav_header_background": "#d2d2d2",
+    # "#e3e3e3",
 }
 
+
 html_sidebars = {
     "**": [
         "globaltoc.html",  # Índice general

docs/getting_started/getting_started.rst

@@ -0,0 +1,11 @@
+Getting started
+===============
+
+The following examples provide a walk-through of phyrisk's functionality, starting with access to hazard indicator data and presenting the hazard inventory then moving onto the running of asset level calculations.
+
+.. toctree::
+   :maxdepth: 2
+
+   hazard_indicators
+   hazard_inventory
+   asset_level_impacts

docs/index.rst

@@ -1,7 +1,7 @@
-Physrisk documentation
+Documentation for physrisk
 ========================================
 
-This website contains the documentation for Physrisk, a calculation engine for Physical Climate Risk.
+This website contains the documentation for physrisk, a calculation engine for physical climate risk.
 
 
 .. _cards-clickable:
@@ -62,24 +62,28 @@ This website contains the documentation for Physrisk, a calculation engine for P
       ^^^
       API reference derived from code.
 
-Physical Risk and Resilience
+Physical risk and resilience
 =============================
 
 Physrisk is a library for assessing the physical effects of climate change and thereby the potential benefit of measures to improve resilience.
 Physrisk is primarily designed to run 'bottom-up' calculations that model the impact of climate hazards on large numbers of individual assets
-(including natural) and operations. These calculations can be used to assess financial risks or socio-economic impacts. To do this physrisk collects:
+(including natural). These calculations can be used to assess financial risks or socio-economic impacts. To do this physrisk collects:
 
 - hazard indicators and
-- models of vulnerability of assets/operations to hazards.
+- models of the vulnerability of assets to hazards.
 
-Hazard indicators are on-boarded from public resources or inferred from climate projections, e.g. from CMIP or CORDEX data sets. Indicators are created from code in the
-[hazard repo](https://github.com/os-climate/hazard) to make calculations as transparent as possible.
+Hazard indicators, that is quantities that quantify a hazard, are on-boarded from public data sets or inferred from climate projections, e.g. from CMIP or CORDEX data sets. In both cases, indicator data is created from code in the
+`hazard repo <https://github.com/os-climate/hazard>`_, open-source to make the data lineage as transparent as possible.
 
-Physrisk is also designed to be a hosted, e.g. to provide on-demand calculations. [physrisk-api](https://github.com/os-climate/physrisk-api) and [physrisk-ui](https://github.com/os-climate/physrisk-ui) provide an example API and user interface.
-A [development version of the UI](https://physrisk-ui-sandbox.apps.odh-cl1.apps.os-climate.org) is hosted by OS-Climate.
+The `physrisk repo <https://github.com/os-climate/physrisk>`_ contains the main calculation engine. 
 
-Please also see the `OSC webpage <https://os-climate.org/physical-risk-resilience/>`_
+Physrisk is also designed to be a hosted, e.g. to provide on-demand calculations; the project is a co-operative of members some of whom need to integrate physical risk calculation into other systems. `physrisk-api <https://github.com/os-climate/physrisk-api>`_ and `physrisk-ui <https://github.com/os-climate/physrisk-ui>`_ provide an example API and user interface.
 
+A `development or 'sandbox' version of the UI <https://physrisk-ui-sandbox.apps.odh-cl1.apps.os-climate.org>`_ is hosted by OS-Climate. Although used for demonstration and test, this is a useful way to explore the available hazard data.
+
+Also see the `OSC webpage <https://os-climate.org/physical-risk-resilience/>`_
+
+The getting-started section contains a number of examples that provide a walk-through of physrisk's functionality, via API then running locally. The methodology document gives a more detailed introduction to the subject and describes the models in more formal detail. The user-guide describes the design and conventions of physrisk and implementation detail for sourcing hazard indicator and vulnerability data; it is there, and in the code, that the details of data sources can be found.
 
 .. image:: images/PRR-5.jpg
   :width: 800
@@ -97,9 +101,9 @@ Contents
 .. toctree::
   :maxdepth: 2
 
-  getting-started
+  getting_started/getting_started.rst
   methodology
-  user-guide
+  user_guide/user_guide.rst
   api/physrisk
 
 Indices and tables

docs/methodology.rst

@@ -1,5 +1,5 @@
 =================================
-Physical Climate Risk methodology
+Physical climate risk methodology
 =================================
 
 :download:`Download PDF <../methodology/PhysicalRiskMethodology.pdf>`