Restructures development guide with subsections

spjuhel · spjuhel · commit e534253c8063 · 2025-02-04T13:47:12.000+01:00
- Fixes links in development guide
- Minor renaming
diff --git a/doc/development/Guide_Euler.ipynb b/doc/development/Guide_Euler.ipynb
@@ -92,7 +92,7 @@
     "\n",
     "### 3. Adjust the Climada configuration\n",
     "\n",
-    "Edit a configuration file according to your needs (see [Guide_Configuration](../guide/Guide_Configuration.ipynb)).\n",
+    "Edit a configuration file according to your needs (see [Guide_Configuration](Guide_Configuration.ipynb)).\n",
     "Create a climada.conf file e.g., in /cluster/home/$USER/.config with the following content:\n",
     "\n",
     "```json\n",
@@ -140,7 +140,7 @@
     "\n",
     "### 1. Load dependencies \n",
     "\n",
-    "See [Load dependencies](#1.-load-dependencies) above."
+    "See [Load dependencies](#load-dependencies) above."
    ]
   },
   {
@@ -159,7 +159,6 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "\n",
     "### 3. Checkout sources\n",
     "\n",
     "```bash\n",
diff --git a/doc/development/coding-in-python.rst b/doc/development/coding-in-python.rst
@@ -0,0 +1,10 @@
+################
+Coding in python
+################
+
+.. toctree::
+   :maxdepth: 1
+
+   Guide_PythonDos-n-Donts
+   Guide_Exception_Logging
+   Performance and Best Practices <Guide_Py_Performance>
diff --git a/doc/development/dev-git.rst b/doc/development/dev-git.rst
@@ -0,0 +1,10 @@
+###############################
+Using git and GitHub to develop
+###############################
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   Development with Git <Guide_Git_Development>
+   Guide_continuous_integration_GitHub_actions
diff --git a/doc/development/index.rst b/doc/development/index.rst
@@ -1,20 +1,15 @@
-.. include:: ../misc/CONTRIBUTING.md
-   :parser: commonmark
+.. include:: ../../CONTRIBUTING.md
+   :parser: myst_parser.sphinx_
 
 .. toctree::
-   :maxdepth: 1
-   :caption: Developer Guide
+   :maxdepth: 2
    :hidden:
 
    Developer guide <Guide_CLIMADA_Development>
-   Development with Git <Guide_Git_Development>
-   Guide_CLIMADA_Tutorial
-   Guide_Configuration
-   Guide_Testing
-   Guide_continuous_integration_GitHub_actions
-   Guide_Review
-   Guide_PythonDos-n-Donts
-   Guide_Exception_Logging
-   Performance and Best Practices <Guide_Py_Performance>
+   Development with Git <dev-git>
+   Coding in python <coding-in-python>
    CLIMADA Coding Conventions <Guide_CLIMADA_conventions>
-   Building the Documentation <../misc/README>
+   Documenting your code <write-documentation>
+   Writing tests for your code <Guide_Testing>
+   Guide_Review
+   Guide_Euler
diff --git a/doc/development/write-documentation.rst b/doc/development/write-documentation.rst
@@ -0,0 +1,9 @@
+###########################
+Documentation writing
+###########################
+
+.. toctree::
+   :maxdepth: 1
+
+   Guide_CLIMADA_Tutorial
+   Building the Documentation <../README>
diff --git a/doc/getting-started/0_10min_climada.ipynb b/doc/getting-started/0_10min_climada.ipynb
diff --git a/doc/getting-started/Guide_Introduction.ipynb b/doc/getting-started/Guide_Introduction.ipynb
@@ -70,7 +70,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "Python 3",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -84,7 +84,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.8"
+   "version": "3.12.6"
   }
  },
  "nbformat": 4,
diff --git a/doc/getting-started/Guide_get_started.ipynb b/doc/getting-started/Guide_get_started.ipynb
@@ -5,7 +5,7 @@
    "id": "trying-bronze",
    "metadata": {},
    "source": [
-    "# Getting started with CLIMADA"
+    "# Climada documentation"
    ]
   },
   {
@@ -42,31 +42,6 @@
     "It is best to have some basic knowledge of Python programming before starting with CLIMADA. But if you need a quick introduction or reminder, have a look at the short [Python Tutorial](../tutorial/0_intro_python.ipynb). Also have a look at the python [Python Dos and Don't](../guide/Guide_PythonDos-n-Donts.ipynb) guide and at the [Python Performance Guide](../guide/Guide_Py_Performance.ipynb) for best practice tips."
    ]
   },
-  {
-   "cell_type": "markdown",
-   "id": "c6ae7939",
-   "metadata": {},
-   "source": [
-    "## Apps for working with CLIMADA\n",
-    "\n",
-    "To work with CLIMADA, you will need an application that supports Jupyter Notebooks.\n",
-    "There are plugins available for nearly every code editor or IDE, but if you are unsure about which to choose, we recommend [JupyterLab](https://jupyterlab.readthedocs.io/en/stable/), [Visual Studio Code](https://code.visualstudio.com/) or [Spyder](https://www.spyder-ide.org/).\n",
-    "It is easy to get confused by all the different softwares and their uses so here is an overview of which tools we use for what:"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "id": "25ab3b98",
-   "metadata": {},
-   "source": [
-    "| Use                                | Tools                | Description | Useful for |\n",
-    "|:----------------------------------|:---------------------|:------------|:-----------|\n",
-    "| Distribution /<br>manage virtual environment<br>& packages | Recommended:<br>Mamba<br>Alternatives:<br>Anaconda|<li>Install climada, manage & use the climada virtual environment, install packages</li><li>Anaconda includes Anaconda navigator, which is a desktop GUI and can be used to launch applications like Jupyter Notebook, Spyder etc.</li></ul>| Climada Users<br>& Developers|\n",
-    "| IDE<br>(Integrated Development Environment)|Recommended:<br>VSCode<br>Alternatives:<br>Spyder<br>JupyterLab<br>PyCharm<br>& many more|<li>Write and run code</li> Useful for Developers:<li>VSCode also has a GUI to commit changes to Git (similar to GitHub Desktop, but in the same place as your code)</li><li>VSCode test explorer shows results for individual tests & any classes and files containing those tests (folders display a failure or pass icon)</li></ul>|Climada Users<br>& Developers|\n",
-    "| Git GUI<br>(Graphical User Interface)|GitHub Desktop<br>Gitkraken|<li>Provides an interface which keeps track of the branch you’re working on, changes you made etc.</li><li>Allows you to commit changes, push to GitHub etc. without having to use command line</li><li>The code itself is not written using these applications but with your IDE of choice(see above)</li></ul>|Climada Developers|\n",
-    "| Continuous integration<br>(CI) server|Jenkins|<li>Automatically checks code changes in GitHub repositories, e.g. when you create a pull request for the develop branch</li><li>Performs static code analysis using pylint</li><li>you don't need to do any installations yourself, this runs automatically when you push new code to GitHub</li><li>see [Continuous Integration and GitHub Actions](../guide/Guide_continuous_integration_GitHub_actions.ipynb)</li></ul>|Climada Developers|"
-   ]
-  },
   {
    "cell_type": "markdown",
    "id": "touched-penetration",
@@ -108,7 +83,7 @@
  ],
  "metadata": {
   "kernelspec": {
-   "display_name": "climada_env",
+   "display_name": "Python 3 (ipykernel)",
    "language": "python",
    "name": "python3"
   },
@@ -122,7 +97,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.8.15 | packaged by conda-forge | (default, Nov 22 2022, 08:49:06) \n[Clang 14.0.6 ]"
+   "version": "3.12.6"
   },
   "vscode": {
    "interpreter": {
diff --git a/doc/index.rst b/doc/index.rst
@@ -129,7 +129,7 @@ specialized applications can be found in the `CLIMADA Petals
 
    Getting started <getting-started/index>
    User Guide <user-guide/index>
-   Development <development/index>
+   Developer Guide <development/index>
    API Reference <api/index>
    About <misc/AUTHORS>
    Changelog <misc/CHANGELOG>
