Finalize Physical Risk handbook/on-boarding guide

[HeatherAck]

• Provide documentation and use case examples
• Define Physical Risk Project governance steps & structure
• Define process for code/model contributors

[negillett]

@joemoorhouse, you currently working on this, right?

[joemoorhouse]

@negillett, yes I think one for me. I am looking ay options for documentation.

Looking at other 'maths-heavy' projects to see what kind of things they do. IBM's Qiskit makes extensive use of Jupyter notebooks:

https://github.com/Qiskit/platypus/blob/aa02f20965bf9a570d6cf1461d20b567a846967a/notebooks/intro/atoms-of-computation.ipynb

And also .rst
https://github.com/Qiskit/qiskit/blob/master/docs/qc_intro.rst

I am thinking one of these two. Any other popular options?

• Need to be able to embed equations + code, 'easily'
• Desirable to be able to visualize in GitHub itself + VS Code etc

[negillett]

Those you've linked look good.
They're using sphinx, which we already have config for and with which I'm most familiar, to generate their primary documentation.

The other suggests it's using platypus, with which I'm unfamiliar, but it seems to be entirely a notebook.

I'd start with sphinx, as it should be sufficient.

We'll probably want something via openapi for physrisk-api. And I'm totally clueless WRT documentation for UI.

[joemoorhouse]

I've kicked off the handbook here using .rst, which I think keeps us Sphinx-friendly.
https://github.com/os-climate/physrisk/blob/main/docs/handbook/onboarding.rst

.rst seems pretty good. My one gripe is that equations don't render in GitHub (some people on-line are quite annoyed about that :)), but sounds like all is fine once we render to HTML, so we can presumably generate a 'fair' HTML version of the handbook and publish somewhere.

[HeatherAck]

@joemoorhouse Looks great! Thanks for all your hard work on this! We can publish HTML version on the OS-C web page under projects, potentially on google drive, or alternatively, Linux Foundation recommends we publish project docs to an Atlassian-based wiki. I need to investigate this option as the FinOS team (another LF program) said many of their members who are financial institutions weren't able to access it.

[DavideFerri]

Hi @joemoorhouse, I have gone through the .rst and I think it's very helpful. Just a few points / questions for you:

1. to showcase the plug & play functionality, I was wondering whether we could explain what the main components of a model are (i.e. hazard component, vulnerability component and financial module), how they work together and how to implement them in the library. Tell me if you disagree, but I think that it would be great if people were able to contribute with their hazard models / vulnerability models here. But to do so they need to know exactly what the inputs / outputs of each module should look like to integrate in the library.

2. Maybe it's just me, but I find it difficult to understand from the file how the user can rely on a default hazard / vulnerability distribution vs using one of her choice (say, a proprietary vulnerability model)

3. I think that HazardEventDistrib and VulnerabilityDistrib should have a consistent naming, would you agree?

4. What happens when there is no appropriate decorator for the specific problem?