Merge pull request #121 from LukasFehring/documentation-review

Documentation review

Author: sarah-segel

README.md

@@ -16,7 +16,7 @@ Following features are provided:
 - A large collection of plugins to explore multiple areas like performance, hyperparameter and
 budget analysis.
 - Save your runs using DeepCAVE's native recorder.
-- Support for many optimizers using converter (e.g., DeepCAVE, SMAC and BOHB).
+- Support for many optimizers using converters (e.g., DeepCAVE, SMAC and BOHB).
 - Select runs directly from a working directory in the interface.
 - Select groups of runs for combined analysis.
 - Modularized plugin structure with access to selected runs/groups to provide maximal flexibility.
@@ -43,6 +43,7 @@ pip install DeepCAVE
 If you want to contribute to DeepCAVE use the following steps instead:
 ```bash
 git clone https://github.com/automl/DeepCAVE.git
+cd DeepCAVE
 conda create -n DeepCAVE python=3.9
 conda activate DeepCAVE
 conda install -c anaconda swig

deepcave/plugins/hyperparameter/pdp.py

@@ -85,6 +85,7 @@ def get_input_layout(register: Callable) -> List[dbc.Row]:
                         [
                             dbc.Label("Budget"),
                             help_button(
+                                "Budget refers to the Multi-Fidelity budget."
                                 "Combined budget means that the trial on the highest"
                                 " evaluated budget is used.\n\n"
                                 "Note: Selecting combined budget might be misleading if"

deepcave/plugins/hyperparameter/symbolic_explanations.py

@@ -89,6 +89,7 @@ def get_input_layout(register: Callable) -> List[Union[dbc.Row, html.Details]]:
                         [
                             dbc.Label("Budget"),
                             help_button(
+                                "Budget refers to the Multi-Fidelity budget."
                                 "Combined budget means that the trial on the highest"
                                 " evaluated budget is used.\n\n"
                                 "Note: Selecting combined budget might be misleading if"

deepcave/plugins/objective/configuration_cube.py

@@ -81,6 +81,7 @@ def get_input_layout(register: Callable) -> List[dbc.Row]:
                         [
                             dbc.Label("Budget"),
                             help_button(
+                                "Budget refers to the Multi-Fidelity budget."
                                 "Combined budget means that the trial on the highest"
                                 " evaluated budget is used.\n\n"
                                 "Note: Selecting combined budget might be misleading if"

deepcave/plugins/summary/footprint.py

@@ -74,6 +74,7 @@ def get_input_layout(register: Callable) -> List[Any]:
                         [
                             dbc.Label("Budget"),
                             help_button(
+                                "Budget refers to the Multi-Fidelity budget."
                                 "Combined budget means that the trial on the highest"
                                 " evaluated budget is used.\n\n"
                                 "Note: Selecting combined budget might be misleading if"

docs/getting_started.rst

@@ -39,6 +39,9 @@ to see the dashboard in action:
 .. image:: images/plugins/general.png
 
 
+Displaying the data is done via plugins. You can select the plugins you want to use in the menu on the left.
+This is further explained in the :ref:`plugins<Displaying Data with Plugins>` section.
+
 DeepCAVE uses runs to interprete data. A run is a collection of trials
 (a configuration with associated costs). Once valid runs (see :ref:`converter<Converters>`) are
 found, you can select them to analyze them further. After selecting runs, you can also add them to

docs/how_to_contribute.rst

@@ -0,0 +1,66 @@
+==================
+How to Contribute
+==================
+We would appreciate your help in making this project better. Whether it's a bug report, new feature, correction, or additional documentation, we greatly value feedback and contributions from our community. If you think you have found a bug, or have a new feature idea, please check for `github issues <github_issues_>`_ and create a new issue if needed. For new feature ideas, open a new issue and setup a development workflow to work on the issue. If you have a correction or addition to the documentation, please submit a pull request.
+
+.. _contribute_fork_project:
+
+Setup Development Workflow
+---------------------------
+The development workflow is based on the "fork-and-pull" Git workflow. A full description of the workflow can be found `here <fork_and_pull_>`_. To contribute to the project, follow these steps:
+
+1. Fork the project.
+2. Install the project in development mode as described in the :ref:`installation` section.
+3. Create a new branch for the new feature on your own fork, note that all changes should be based on the `development` branch.
+4. Make your changes and commit them to your branch.
+5. Push your changes to your fork.
+6. Open a pull request from your fork to the main repository's `development` branch.
+
+
+
+.. _contribute_unit_tests:
+
+Extend Unit Tests 
+------------------
+When adding new features or making changes to the codebase, it is important to add unit tests and check for mistakes revealed by preexisting test cases. This project uses `unittest` for testing. To run the test suite, use the following command:
+
+.. code-block:: bash
+
+    python -m unittest discover -s tests
+
+
+.. _contribute_update_documentation:
+
+Update Documentation
+---------------------
+
+The documentation is written in reStructuredText and uses Sphinx to generate HTML documentation. To build the documentation, use the following command:
+
+.. code-block:: bash
+
+    make docs
+
+
+.. _contribute_pre_commit_hook:
+
+Pre-Commit Hook
+---------------
+Before submitting a pull request, you should run the pre-commit hook to check for formatting errors and run the test suite. 
+
+.. _contribute_pull_request:
+
+Create Pull Request
+--------------------
+
+After making changes to the codebase, you can submit a pull request. Your pull request will be reviewed by the maintainers, and if everything looks good, it will be merged. Before submitting a pull request, please make sure of the following:
+
+- Make sure the you reference the issue in the pull request.
+- The pull request should include tests for the new feature or bug fix.
+- The pull request should include documentation for the new feature or bug fix.
+- All tests should pass.
+- Make sure to select the correct source and destination repositories and according branches.
+- The pull request should include a description of the change and the reason for the change.
+
+
+.. _github_issues: https://github.com/automl/DeepCAVE/issues
+.. _fork_and_pull: https://reflectoring.io/github-fork-and-pull/

docs/index.rst

@@ -14,6 +14,7 @@ Home
    examples/index
    plugins/index
    converters
+   how_to_contribute
    api
    glossary
    faq

docs/plugins/index.rst

@@ -1,5 +1,5 @@
-Plugins
-=======
+Displaying Data with Plugins
+============================
 
 .. toctree::
    :hidden:

docs/plugins/overview.rst

@@ -23,7 +23,7 @@ This plugin is capable of answering following questions:
 * Is the configuration space as expected?
 * How many trials have been successful/unsuccessful?
 * Why did certain trials crash?
-* On which budgets were the configurations evaluated?
+* On which Multi Fidelity budgets were the configurations evaluated?
 
 
 Quick Information
@@ -36,7 +36,9 @@ the runs were last updated and a handy quick link to the best **Configuration**.
 Meta
 ----
 Next we show some meta information regarding your runs. Notably, you can see information such as the
-possible **budget** allocations that were considered during the run.
+possible **budget** allocations that were considered during the run. The **budget** is the amount of
+resources that were allocated to a configuration as it was beeing evaluated using a Multi-Fidelity 
+Approach.
 
 
 Objectives