docs: website building docs

Author: janfb

docs/README.md

@@ -1,28 +1,45 @@
 # Documentation
 
-The documentation is available at: <http://sbi-dev.github.io/sbi>
+The documentation is available at: [sbi-dev.github.io/sbi](http://sbi-dev.github.io/sbi)
 
 ## Building the Documentation
 
-You can build the docs locally by running the following command from this subfolder:
+We use [`mike`](https://github.com/jimporter/mike) to manage, build, and deploy our
+documentation with [`mkdocs`](https://www.mkdocs.org/). To build the documentation
+locally, follow these steps:
 
-```bash
-jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
-jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
-mkdocs serve
-```
+1. Install the documentation dependencies:
 
-The docs can be updated to GitHub using:
+    ```bash
+    python -m pip install .[doc]
+    ```
 
-```bash
-jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
-jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
-mkdocs gh-deploy
-```
+2. Convert the current version of the documentation notebooks to markdown and build the
+   website locally using `mike`:
+
+    ```bash
+    jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorials/
+    jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
+    mike serve
+    ```
+
+### Deployment
+
+Website deployment is managed with `mike` and happens automatically:
+
+- With every push to `main`, a `dev` version of the most recent documentation is built.
+- With every new published **release**, the current documentation is deployed on the
+  website.
+
+Thus, the documentation on the website always refers to the latest release, and not
+necessarily to the version on `main`.
 
 ## Contributing FAQ
 
-Create a new markdown file named `question_XX.md` in the `docs/faq` folder, where `XX`
-is a running index for the questions. The file should start with the question as title
-(i.e. starting with a `#`) and then have the answer below. Additionally, you need to
-add a link to your question in the markdown file `docs/faq.md`.
+We welcome contributions to our list of frequently asked questions. To contribute:
+
+1. Create a new markdown file named `question_XX.md` in the `docs/faq` folder, where
+   `XX` is a running index for the questions.
+2. The file should start with the question as the title (i.e. starting with a `#`) and
+   then have the answer below.
+3. Add a link to your question in the [`docs/faq.md`] file using the same index.

docs/docs/contribute.md

@@ -211,19 +211,31 @@ fails (xfailed).
   commenting on the PR.
 
 ## Contributing to the documentation
-Most of the documentation for `sbi` is written in markdown and the website is
-generated using `mkdocs` with `mkdocstrings`. To work on improvements of the
-documentation, you should first  install the `doc` dependencies:
-```
+
+Most of the documentation for `sbi` is written in markdown and the website is generated
+using `mkdocs` with `mkdocstrings` and `mike`. The tutorials and examples are converted
+from jupyter notebooks into markdown files to be shown on the website. To work on
+improvements of the documentation, you should first  install the `doc` dependencies:
+
+```bash
 pip install -e ".[doc]"
 ```
-Then, you can run the command on your terminal
+
+Then, you can build the website locally by executing in the `docs` folder
+
+```bash
+mike serve
 ```
+
+This will build the website on a local host address shown in the terminal. Changes to
+the website files or a browser refresh will immediately rebuild the website.
+
+If you want to build the latest version of the tutorial notebooks, you need to convert
+them to markdown first:
+
+```bash
 cd docs
 jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
 jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorials/
-mkdocs serve
+mike serve
 ```
-and open a browser on the page proposed by `mkdocs`. Now, whenever you
-make changes to the markdown files of the documentation, you can see the results
-almost immediately in the browser.