🔧 Configure readthedocs documentation build

.readthedocs.yml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.9"
+  jobs:
+    pre_build:
+      # Generate the Sphinx configuration for this Jupyter Book so it builds.
+      # https://jupyterbook.org/en/stable/publish/readthedocs.html
+      - "jupyter-book config sphinx docs/"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+      - docs
+
+sphinx:
+  builder: html
+  fail_on_warning: true

docs/CONTRIBUTING.md

@@ -5,14 +5,14 @@ including some that don't require you to write a single line of code.
 
 ## 📝 Types of contributions
 
-## Discussions 🎉
+### Discussions 🎉
 
 Discussions are where we have conversations.
 
 If have a great new idea, or want to share something amazing with the community,
 join us in [discussions](https://github.com/weiji14/zen3geo/discussions).
 
-## Issues 🐞
+### Issues 🐞
 
 [Issues](https://docs.github.com/en/github/managing-your-work-on-github/about-issues)
 are used to track tasks that contributors can help with.
@@ -22,7 +22,7 @@ search open issues to see if someone else has reported the same thing. If it's
 something new, [open an issue](https://github.com/weiji14/zen3geo/issues/new/choose)!
 We'll use the issue to have a conversation about the problem you want to fix.
 
-## Pull requests 🛠️
+### Pull requests 🛠️
 
 A [pull request](https://docs.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests)
 is a way to suggest changes in our repository.
@@ -31,13 +31,14 @@ When we merge those changes, they should be deployed to the live site within a f
 To learn more about opening a pull request in this repo,
 see [Opening a pull request](#opening-a-pull-request) below.
 
-## Translations 🌏
+### Translations 🌏
 
 人虽有南北之分，但佛性本无南北。
 
 Yes, the source content in this repository is mostly written in English,
 but we welcome folks from across the world! Please reach out if you have experience in translations and are interested in contributing!
 
+---
 
 ## 👐 Opening a Pull Request
 
@@ -91,6 +92,42 @@ but we welcome folks from across the world! Please reach out if you have experie
    will be notified about your great new addition and will get back to you on
    the next steps.
 
+---
+
+## 🏠 Running things locally
+
+This project uses [``poetry``](https://python-poetry.org/docs/master/) for
+installing Python dependencies required in ``zen3geo``, as well as the
+development and documentation-related dependencies.
+
+### Cloning the repository ♊
+
+```
+git clone git@github.com:weiji14/zen3geo.git
+cd zen3geo
+```
+
+### Setup virtual environment ☁️
+
+```
+mamba create --name zen3geo python=3.9
+mamba activate
+
+pip install poetry==1.2.0b1
+poetry install
+```
+
+### Building documentation 📖
+
+```
+poetry install --extras=docs  # or `pip install .[docs]`
+jupyter-book build docs/
+```
+
+Then open ``docs/_build/html/index.html`` in your browser to see the docs.
+
+---
+
 ## 🥳 And that's it!
 
 You're now part of the zen3geo community ✨