Working on the overall repository

CODE_OF_CONDUCT

@@ -0,0 +1,8 @@
+Code of conduct
+---------------
+
+This tutorial adheres to the [EuroSciPy Code of
+Conduct](https://euroscipy.org/2024/code_of_conduct.html). We are committed to
+providing a welcoming and inclusive environment for all participants. Please
+make sure to familiarize yourself with the conference's guidelines to ensure a
+positive experience for everyone.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Nikoleta Glynatsi and Sebastian Berg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,2 +1,39 @@
-# a-hitchhikers-guide-to-contributing-to-open-source
-Open source material that will help you transition from user to contributor. Learn to use Git, document and test code, improve documentation, and master GitHub.
+# A Hitchhiker's Guide to Contributing to Open Source
+
+Open source material that will help you transition from user to contributor.
+Learn to use Git, document and test code, improve documentation, and master
+GitHub.
+
+This repository contains the files necessary for a mock Python package called
+`listwiz`. It is a package that allows us to handle and manipulate lists.
+
+Any Python project has its own repository and slightly different style, but many
+things remain the same across projects. This project follows the recommended
+structure. Below, you can see the various files and folders of the project along
+with their purposes:
+
+- `.github/workflows`: This directory contains files for running Continuous
+  Integration (CI).
+- `docs`: Contains all necessary files for the online documentation of the
+  package. This package is built using Sphinx, and you can see the online
+  documentation here:
+  [https://a-hitchhikers-guide-to-contributing-to-open-source.readthedocs.io/en/latest/](https://a-hitchhikers-guide-to-contributing-to-open-source.readthedocs.io/en/latest/).
+- `src`: The folder with the source code of the package. The convention is to
+  name this folder `src/<name_of_package>`. In this case, it's `src/listwiz`.
+- `tests`: This folder contains all the tests for the source code. We usually
+  aim for each file in `src` to have an associated test file in the `tests`
+  folder.
+- `.gitignore`: This file lists all the files we want Git to ignore. For
+  example, our Python package generates many auxiliary files, which are listed
+  here because we want to ignore them and not push them to our online
+  repository.
+- `.readthedocs.yaml`: A file that allows us to deploy the online documentation.
+- `CODE_OF_CONDUCT`: The file that outlines the expected behavior for
+  contributors/attendees.
+- `LICENSE`: The file that contains the license information. Licenses are not
+  restrictive, even though some people seem to think so. A license lets us know
+  and informs users when it's okay to use a package and who has the original
+  rights.
+- `pyproject.toml`: The file that is run when we install the package.
+- `README.md`: The file that provides an overview of the project and
+  instructions for getting started.

docs/build/html/_sources/contributing/branching.rst.txt

@@ -0,0 +1,23 @@
+.. _Branching:
+
+2. Creating a branch
+---------------------
+
+Before we start making changes to the source code, the first thing we will do is
+create a new branch. This is because we want to keep the changes we are about to
+make separate from the main source code. To do this, first change directory into
+the source code::
+
+    $ cd a-hitchhikers-guide-to-contributing-to-open-source
+
+Now, to create a new branch, type the following::
+
+        $ git branch the-name-of-the-branch
+
+Note that the name of the branch should be descriptive of the changes you are
+going to make. For example, if you are going to add a new function to the source
+code, you could name the branch :code:`implementing-new-function`.
+
+Now checkout to that branch::
+
+    $ git checkout the-name-of-the-branch

docs/build/html/_sources/contributing/contributing_docs.rst.txt

@@ -0,0 +1,89 @@
+.. |uncheck| raw:: html
+
+    <input type="checkbox">
+
+.. _ContributingDocs:
+
+3. Contributing to the documentation
+-------------------------------------
+
+In the issues section of the project, you can find issues that are labeled
+:code:`documentation`. These are issues that are related to the documentation of
+the project. You can choose one of these issues to work on.
+
+The documentation is a crucial part of any open-source project. It helps users
+understand how to use the software and how to contribute to it.
+
+All the files for the documentation are in the :code:`docs` directory. The
+documentation is written in `reStructuredText
+<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_. The
+documentation is built using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+
+In order to modify the documentation, you need to change the files in the
+:code:`docs` directory. Open the project in your preferred editor. If you do not
+have a preferred editor `Visual Studio Code <https://code.visualstudio.com>`_ is
+recommended.
+
+Take a few minutes to familiarize yourself with the structure of the
+documentation. The main file for the documentation is :code:`index.rst` which is
+in the :code:`docs` directory. This file includes all the other files in the
+documentation. The documentation is split into different sections, each of which
+is in a separate folder in the :code:`docs` directory.
+
+
+Checking the modification
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To build the documentation, the first thing you need to do is to download
+`Sphinx <https://www.sphinx-doc.org/en/master/>`_. You can do this via `pip`::
+
+    $ python -m pip install sphinx
+
+To build the documentation navigate to the :code:`docs` directory::
+
+    $ cd docs
+
+and run the command::
+
+    $ make html
+    Running Sphinx v5.0.2
+    loading pickled environment... done
+    building [mo]: targets for 0 po files that are out of date
+    building [html]: targets for 0 source files that are out of date
+    updating environment: 0 added, 0 changed, 0 removed
+    looking for now-outdated files... none found
+    no targets are out of date.
+    build succeeded.
+
+    The HTML pages are in build/html.
+
+You can open :code:`_build/html/index.html` in a browser to see the
+documentation locally which should include the changes you made.
+
+
+Committing the change
+^^^^^^^^^^^^^^^^^^^^^
+
+Once you are done with your changes, you need to commit them. First, you need to
+**stage** the files you have changed. To do this, run the following command::
+
+    $ git add <name of the file tou want to commit>
+
+Do this for all the files you have changed. Once you have staged all the files,
+you can commit them::
+
+    $ git commit
+
+This will open a text editor where you can write your commit title and message.
+
+
+Checklist
+^^^^^^^^^
+
+| |uncheck| Choose an issue labeled :code:`documentation` from the issues section.
+| |uncheck| Familiarize yourself with the structure of the documentation.
+| |uncheck| Make the necessary changes to the documentation.
+| |uncheck| Build the documentation using `Sphinx <https://www.sphinx-doc.org/en/master/>`_.
+| |uncheck| Check the changes you made by opening :code:`_build/html/index.html` in a browser.
+| |uncheck| Add the changes to the staging area.
+| |uncheck| Commit the changes.

docs/build/html/_sources/contributing/contributing_function.rst.txt

@@ -0,0 +1,99 @@
+.. |uncheck| raw:: html
+
+    <input type="checkbox">
+
+.. _ContributingFunction:
+
+5. Contributing a new function
+-------------------------------
+
+Navigate to the issues tab of the repository and find an issue that you would
+like to work on. Some of these issues are tagged as :code:`enhancement`. The
+issue will have a description of the function that needs to be implemented, and
+where the function code should be included.
+
+
+Install the package in development mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To contribute any source code such a test, you need to install the package in
+development mode. To do this, run the following command from the root of the
+project folder::
+
+    $ pip install -e .
+
+
+Implementing your function
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+In your function you need to remember to include a docstring that describes what
+the function does. This is important for users of the software to understand how
+to use the function. The docstring should be in the following format::
+
+    def function_name(arguments):
+        """
+        Description of the function.
+
+        Parameters
+        ----------
+        arguments : type
+            Description of the argument.
+
+        Returns
+        -------
+        type
+            Description of the return value.
+        """
+
+        # code for the function
+
+
+Documenting your function
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+Testing your function
+^^^^^^^^^^^^^^^^^^^^^
+
+Before you commit your changes, you need to test your function. To do this, you
+need to run the test suite. The test suite is in the :code:`tests` directory.
+The test suite is written using `pytest <https://docs.pytest.org/en/stable/>`_.
+To run the test suite, run the command from the root of the project folder::
+
+    $ pytest tests
+    ============================= test session starts ==============================
+    platform linux -- Python 3.8.5, pytest-6.2.2, pluggy-0.13.1
+    rootdir: /home/nikoleta/Documents/a-hitchhikers-guide-to-contributing-to-open-source
+    collected 0 items
+
+    ============================== no tests ran in 0.01s ==============================
+
+
+Committing the change
+^^^^^^^^^^^^^^^^^^^^^
+
+Once you are done with your changes, you need to commit them. First, you need to
+**stage** the files you have changed. To do this, run the following command::
+
+    $ git add <name of the file tou want to commit>
+
+Do this for all the files you have changed. Once you have staged all the files,
+you can commit them::
+
+    $ git commit
+
+This will open a text editor where you can write your commit title and message.
+
+
+Checklist
+^^^^^^^^^
+
+| |uncheck| Choose an issue labeled :code:`enhancement` from the issues section.
+| |uncheck| Familiarize yourself with the structure of the source code.
+| |uncheck| Install the package in development mode.
+| |uncheck| Implement the new function.
+| |uncheck| Include a docstring in the function.
+| |uncheck| Implement a test for your new function.
+| |uncheck| Test the function using the test suite.
+| |uncheck| Add the changes to the staging area.
+| |uncheck| Commit the changes.

docs/build/html/_sources/contributing/contributing_test.rst.txt

@@ -0,0 +1,60 @@
+.. |uncheck| raw:: html
+
+    <input type="checkbox">
+
+.. _ContributingTest:
+
+4. Contributing a test
+----------------------
+
+Navigate to the issues tab of the repository and find an issue that you would
+like to work on. Some of these issues are tagged as :code:`Tests`. The
+issue will have a description of the function that needs to be implemented, and
+where the function code should be included.
+
+Install the package in development mode
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To contribute any source code such a test, you need to install the package in
+development mode. To do this, run the following command from the root of the
+project folder::
+
+    $ pip install -e .
+
+
+Running the test suite
+^^^^^^^^^^^^^^^^^^^^^^
+
+Once you have implemented your test you need to run the test suite to ensure
+that your test is working correctly. The test suite is written using `pytest
+<https://docs.pytest.org/en/stable/>`_. To run it, , run the following command
+from the root of the project folder::
+
+    $ pytest tests
+
+
+Committing the change
+^^^^^^^^^^^^^^^^^^^^^
+
+Once you are done with your changes, you need to commit them. First, you need to
+**stage** the files you have changed. To do this, run the following command::
+
+    $ git add <name of the file tou want to commit>
+
+Do this for all the files you have changed. Once you have staged all the files,
+you can commit them::
+
+    $ git commit
+
+This will open a text editor where you can write your commit title and message.
+
+
+Checklist
+^^^^^^^^^
+
+| |uncheck| Choose an issue labeled :code:`Tests` from the issues section.
+| |uncheck| Install the package in development mode.
+| |uncheck| Implement the test.
+| |uncheck| Run the test suite.
+| |uncheck| Add the changes to the staging area.
+| |uncheck| Commit the changes.