Add contributing guidelines to the documentation (#157)

README.md

@@ -35,7 +35,7 @@ New system models and controllers can be developed using the existing ones as te
 
 Contributing
 ------------
-If you'd like to help us develop motulator, please have a look at these [guidelines](https://github.com/Aalto-Electric-Drives/motulator/blob/main/CONTRIBUTING.md) first.
+If you would like to help us develop motulator, please have a look at these [guidelines](https://aalto-electric-drives.github.io/motulator/contributing.html) first.
 
 Contributors
 ------------

docs/source/contributing.rst

@@ -0,0 +1,42 @@
+Contributing
+============
+
+Style Guide
+-----------
+
+We follow the `Style Guide for Python Code PEP8 <https://peps.python.org/pep-0008/>`_. Furthermore, we use the `YAPF Python code formatter <https://github.com/google/yapf>`_, configured based on the PEP8 conventions in the ``pyproject.toml`` file. Public methods and classes should have proper `docstrings <https://peps.python.org/pep-0257/>`_, formatted according to the `NumPy docstring guide <https://numpydoc.readthedocs.io/en/latest/format.html>`_. 
+
+`Sphinx <https://www.sphinx-doc.org>`_ is used to auto-generate documentation. We use `Sphinx-Gallery <https://sphinx-gallery.github.io/stable/index.html>`_ to automatically generate the `examples <https://aalto-electric-drives.github.io/motulator/drive_examples/index.html>`_ from the scripts in the ``examples`` folder. The format of the example scripts is essential for their proper rendering in the documentation (see the existing example scripts). 
+
+Install Optional Dependencies
+-----------------------------
+
+We recommend to install the ``dev`` dependencies (see also :doc:`/installation`). To enable YAPF in VS Code, you can install the `YAPF extension <https://marketplace.visualstudio.com/items?itemName=eeyore.yapf>`_. This extension will automatically format the code according when you save the file.
+
+If you aim to work with the documentation, install also the ``doc`` dependencies. For previewing the documentation in VS Code, you can install the `Esbonio extension <https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio>`_. Alternatively, you can build the documentation locally using the command ``make html`` in the ``docs`` directory. The documentation will be built in the ``docs/build`` directory. 
+
+
+Submitting a Bug Report or a Feature Request
+--------------------------------------------
+
+If you have found bugs or have feature requests, please submit them to the `issue tracker <https://github.com/Aalto-Electric-Drives/motulator/issues>`_. If you are reporting a bug, please include the following in your report:
+
+- Name and version of your operating system.
+- Any relevant details about your local setup, such as the Python interpreter version and installed libraries.
+- A short reproducible code snippet, so that anyone can reproduce the bug easily. 
+- Try to be specific about what functions are involved and the shape of the data, especially when including a code snippet is not feasible.
+- Provide the full traceback to any exceptions that were raised.
+
+Workflow for Contributing
+-------------------------
+
+When contributing code, please follow this workflow:
+
+1. Create a new `issue <https://guides.github.com/features/issues/>`_ to discuss your proposal before starting.
+2. Create your own fork and clone the repository to your local machine.
+3. Commit and push your changes to your fork.
+4. When your code is finished, create a pull request.
+
+Once a pull request has been created, it will be reviewed, and changes might be suggested, which you can make by simply adding new commits to your branch. After the successful review, we will merge your changes into the main repository.
+
+We aim to keep the codebase clean and maintainable. Therefore, we may not be able to accept all contributions (even if they are well-written and feasible). For this reason, it is advisable to discuss possible contributions beforehand in an issue.

docs/source/index.rst

@@ -1,7 +1,7 @@
 *motulator:* Motor Drive and Grid Converter Simulator in Python
 ===============================================================
 
-This open-source software includes simulation models and controllers for electric machine drives and grid converter systems. The machine models include an induction machine, a synchronous reluctance machine, and a permanent-magnet synchronous machine. Various subsystem models are provided for modeling grid converter systems, such as an LCL filter connected to an inductive-resistive grid.
+This open-source software includes simulation models and control methods for electric machine drives and grid converter systems. The machine models include an induction machine, a synchronous reluctance machine, and a permanent-magnet synchronous machine. For modeling grid converter systems, various subsystem models are provided, such as an LCL filter connected to an inductive-resistive grid.
 
 The system models are simulated in the continuous-time domain while the control methods run in discrete time. The default solver is the explicit Runge-Kutta method of order 5(4) from `scipy.integrate.solve_ivp`_. A number of control methods are provided as examples. The example methods aim to be simple yet feasible. 
 
@@ -15,6 +15,7 @@ The system models are simulated in the continuous-time domain while the control
 
    installation
    usage
+   contributing
 
 .. toctree:: 
    :titlesonly:

docs/source/installation.rst

@@ -1,17 +1,19 @@
 Installation
 ============
-First, install Python on your computer. On Windows and Mac systems, you can install Python from the official website (https://www.python.org/). On Linux systems, Python is typically preinstalled. 
+
+First, install Python on your computer. On Windows and Mac systems, you can install it from the `Python official website <https://www.python.org/>`_. On Linux systems, Python is typically preinstalled. 
 
 For plotting figures in Python, a graphical user interface (GUI) library is required. The *Tkinter* GUI library comes by default with Python on Windows and Mac systems. On some Linux systems, you may need to install it separately. On Ubuntu, you can install it with the command::
 
    sudo apt install python3-tk
 
-Alternatively, you can use another GUI library such as *PyQt6* (https://pypi.org/project/PyQt6/). 
+Alternatively, you can use another GUI library such as `PyQt6 <https://pypi.org/project/PyQt6/>`_. 
 
 Install *motulator* using one of the following options. 
 
 Option 1: Use pip
 -----------------
+
 The simplest way to install *motulator* is to use ``pip``. Ensure that you have the latest ``pip``, which can be updated with the command::
 
    pip install --upgrade pip
@@ -21,31 +23,25 @@ Then, install *motulator*::
    pip install motulator
 
 .. note::
-   Instead of global installation described above, using a virtual environment is generally recommended. For more information, see https://packaging.python.org/guides/installing-using-pip-and-virtual-environments. Virtual environments are easiest to create and manage using some integrated development environment (IDE), see Option 2 below.
+   Instead of global installation described above, using a `virtual environment <https://packaging.python.org/guides/installing-using-pip-and-virtual-environments>`_ is generally recommended. Virtual environments are easiest to create and manage using some integrated development environment (IDE), see Option 2 below.
 
 Option 2: Clone the Repository
 ------------------------------
-For developers and advanced users, we recommended cloning the repository from GitHub. This option allows you to get the most recent version of the repository. Furthermore, you can then modify the system models and example controllers. It is also advisable to use a virtual environment to avoid conflicts with other Python packages. 
 
-Several powerful open-source IDEs are available for Python. The following instructions are for VS Code (https://code.visualstudio.com):
+For developers and advanced users, we recommend cloning the repository from GitHub. This option allows you to get the most recent version of the repository. Furthermore, you can then modify the system models and example controllers. It is also advisable to use a virtual environment to avoid conflicts with other Python packages. 
+
+Several powerful open-source IDEs are available for Python. The following instructions are for `VS Code <https://code.visualstudio.com>`_:
 
 1)	Install VS Code, Python, and ``git`` on your computer. Install also the recommended Python extensions in VS Code.
-2) Clone the project::
+2) Clone the project (or fork it first and then clone your fork) using the command::
     
       git clone https://github.com/Aalto-Electric-Drives/motulator
 
-   This will create a folder called *motulator* in your current directory. 
-
+   This will create a folder called *motulator* in your current directory.
 3) Launch VS Code from the cloned project's root directory on the command line (or choose the proper directory after launching VS Code).
-4) Create a virtual environment in the workspace using the instructions provided here: https://code.visualstudio.com/docs/python/environments.
+4) `Create a virtual environment <https://code.visualstudio.com/docs/python/environments>`_ in the workspace.
 5) Enable installation of optional dependencies from ``pyproject.toml`` (selecting at least ``dev`` is recommended). Alternatively, for installing the project with its core dependencies, you may run the command ``pip install .`` in the VS Code terminal after the virtual environment is created and activated (or to include optional dependencies, run ``pip install .[dev,doc]``).
 
 After completing the above steps, the virtual environment can be found in the ``.venv`` directory at the root of the repository. Now you should be able to run all the examples as well as to modify the existing code. When you start VS Code next time, it will automatically detect the virtual environment and use it. If you installed the ``dev`` dependencies, you can also use the interactive IPython console (click on the *Play* button dropdown menu in VS Code). 
 
-If you use Windows, you may need to change the default terminal from the PowerShell to the Command Prompt (press Ctrl+Shift+P for the command palette and search for *Terminal: Select Default Profile*). We hope that these instructions allow you to create a virtual environment and start working on the project. Similar steps can be followed for other IDEs.
-
-Notes for Developers
-^^^^^^^^^^^^^^^^^^^^
-We recommend to install the ``dev`` dependencies. In this project, we use the YAPF Python code formatter (https://github.com/google/yapf), configured based on the PEP8 coding conventions (https://peps.python.org/pep-0008/). To enable YAPF in VS Code, you need to install the YAPF extension (https://marketplace.visualstudio.com/items?itemName=eeyore.yapf). 
-
-If you aim to work with the documentation, install also the ``doc`` dependencies. For previewing the documentation in VS Code, you can install the Esbonio extension (https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio). Alternatively, you can build the documentation locally using the command ``make html`` in the ``docs`` directory. The documentation will be built in the ``docs/build`` directory.
+If you use Windows, you may need to change the default terminal from the PowerShell to the Command Prompt (press Ctrl+Shift+P for the command palette and search for *Terminal: Select Default Profile*). We hope that these instructions allow you to create a virtual environment and start working on the project. Similar steps can be followed for other IDEs.