User Guide Updates (#2257)

Update sections, remove Execution Modes section, Add What's New section - Updated Settings section - Updated Settings up Consoles and External Tools section - Took relevant stuff from Execution Modes section into Setting Up Consoles and External Tools section - Removed Execution Modes section - Added What's New? section, which shows the Changelog.md - Removed created dates from start of files - Capitalized all main headers - Updated some links - Fixed some Sphinx warnings by editing docstrings when building the html docs Re Issue #2156
spine-tools · Aug 16, 2023 · 20c8ce0 · 20c8ce0
1 parent 3c3580f
commit 20c8ce0
Show file tree

Hide file tree

Showing 35 changed files with 333 additions and 328 deletions.
diff --git a/docs/source/contribution_guide.rst b/docs/source/contribution_guide.rst
@@ -1,15 +1,14 @@
 ..  Contribution guide
-    Created: 19.6.2018
 
 .. _Qt Style Sheets: http://doc.qt.io/qt-5/stylesheet.html
 .. _PEP-8: https://www.python.org/dev/peps/pep-0008/
 .. _Google style: http://google.github.io/styleguide/pyguide.html
 
 .. _Contribution Guide:
 
-************************************
-Contribution Guide for Spine Toolbox
-************************************
+******************
+Contribution Guide
+******************
 All are welcome to contribute! This guide is based on a set of best practices for open source projects [JF18]_.
 
 Reporting Bugs

diff --git a/docs/source/data_import_export.rst b/docs/source/data_import_export.rst
@@ -1,5 +1,4 @@
 ..  Importing and exporting data
-    Created: 15.5.2019
 
 .. |open-folder| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg
    :width: 16
@@ -10,7 +9,7 @@
 
 
 ****************************
-Importing and exporting data
+Importing and Exporting Data
 ****************************
 
 This section explains the different ways of importing and exporting data to and from a Spine database.
@@ -386,7 +385,7 @@ GAMS gdx export
 .. note::
    You need to have GAMS installed to use this functionality.
    However, you do not need to own a GAMS license as the demo version works just as well.
-   See :ref:`Setting up External Tools` for more information.
+   See :ref:`Setting up Consoles and External Tools` for more information.
 
 The gdx backend turns the output tables to GAMS sets, parameters and scalars following the rules below:
 

diff --git a/docs/source/developer_documentation.rst b/docs/source/developer_documentation.rst
@@ -1,4 +1,4 @@
-Developer documentation
+Developer Documentation
 =======================
 
 Here you can find developer specific documentation on Spine Toolbox.

diff --git a/docs/source/execution_modes.rst b/docs/source/execution_modes.rst
diff --git a/docs/source/execution_tests.rst b/docs/source/execution_tests.rst
@@ -1,6 +1,6 @@
 .. _Execution tests:
 
-Execution tests
+Execution Tests
 ===============
 
 Toolbox contains *execution tests* that test entire workflows in the headless mode.

diff --git a/docs/source/getting_started.rst b/docs/source/getting_started.rst
@@ -35,7 +35,7 @@ Welcome to the Spine Toolbox's getting started guide.
 In this guide you will learn two ways of running a `"Hello, World!" program
 <https://en.wikipedia.org/wiki/%22Hello,_World!%22_program>`_ on Spine Toolbox.
 If you need help on how to run **SpineOpt.jl** using Spine Toolbox, see chapter
-:ref:`How to set up SpineOpt.jl`. For small example projects utilizing **SpineOpt.jl**, see `SpineOpt tutorials
+:ref:`How to Set up SpineOpt.jl`. For small example projects utilizing **SpineOpt.jl**, see `SpineOpt tutorials
 <https://spine-tools.github.io/SpineOpt.jl/latest/tutorial/simple_system/>`_.
 
 This chapter introduces the following topics:
@@ -205,7 +205,7 @@ Once the execution is finished, you can see the details about the item execution
 
 |
 
-.. note:: For more information about execution modes in Spine Toolbox, please see :ref:`Setting Up External Tools`
+.. note:: For more information about setting up Consoles in Spine Toolbox, please see :ref:`Setting up Consoles and External Tools`
    for help.
 
 Congratulations, you just executed your first Spine Toolbox project.
@@ -321,7 +321,7 @@ Press |execute| once again. The project will be executed successfully this time:
 That's all for now. I hope you've enjoyed following this guide as much as I enjoyed writing it. See you next time.
 
 Where to next: If you need help on how to set up and run **SpineOpt.jl** using Spine Toolbox, see chapter
-:ref:`How to set up SpineOpt.jl`. After setting up SpineOpt, there are three tutorials over on **SpineOpt.jl**'s
+:ref:`How to Set up SpineOpt.jl`. After setting up SpineOpt, there are three tutorials over on **SpineOpt.jl**'s
 documentation that will help you get started on using SpineOpt in Spine Toolbox:
 `Simple system
 <https://spine-tools.github.io/SpineOpt.jl/latest/tutorial/simple_system/>`_,

diff --git a/docs/source/how_to_run_spineopt.rst b/docs/source/how_to_run_spineopt.rst
@@ -1,13 +1,12 @@
-.. How to set up SpineOpt.jl documentation
-   Created 26.5.2021
+.. How to Set up SpineOpt.jl documentation
 
 .. |execute| image:: ../../spinetoolbox/ui/resources/menu_icons/play-circle-solid.svg
              :width: 16
 
-.. _How to set up SpineOpt.jl:
+.. _How to Set up SpineOpt.jl:
 
 *************************
-How to set up SpineOpt.jl
+How to Set up SpineOpt.jl
 *************************
 
 #. Install Julia (v1.6 or later) from `<https://julialang.org/downloads/>`_ if you don't have one.
@@ -17,17 +16,17 @@ How to set up SpineOpt.jl
 
 #. Create a new project (**File -> New project...**)
 
-#. Select **File -> Settings** from the main menu and open the `Tools` page.
+#. Select **File -> Settings** from the main menu and open the *Tools* page.
 
-#. Set a path to a Julia executable to the appropriate line edit (e.g. ``C:/Julia-1.5.4/bin/julia.exe``).
+#. Set a path to a Julia executable to the appropriate line edit (e.g. `C:/Julia-1.6.0/bin/julia.exe`).
    Your selections should look similar to this now.
 
-   .. image:: img/settings_tools_filled_for_spineopt_github.png
+   .. image:: img/settings_tools_default.png
       :align: center
 
 #. *[Optional]* If you want to install and run SpineOpt in a specific Julia project environment (the place for
-   ``Project.toml`` and ``Manifest.toml``), you can set the path to the environment folder to the line edit just below the
-   Julia executable (the one that says `Using Julia default project`).
+   `Project.toml` and `Manifest.toml`), you can set the path to the environment folder to the line edit just below the
+   Julia executable (the one that says *Using Julia default project*).
 
 #. Next, you need to install **SpineOpt.jl** package for the Julia you just selected for Spine Toolbox. You can do
    this manually by `following the instructions <https://github.com/spine-tools/SpineOpt.jl#installation>`_
@@ -49,7 +48,7 @@ Spine Toolbox and Julia are now correctly set up for running **SpineOpt.jl**. Ne
 `Create a project workflow using SpineOpt.jl <https://spine-tools.github.io/SpineOpt.jl/latest/getting_started/setup_workflow/>`_
 (takes you to SpineOpt documentation). See also `Tutorials
 <https://spine-tools.github.io/SpineOpt.jl/latest/tutorial/simple_system/>`_ in SpineOpt documentation for more advanced
-use cases. For more information on how to select a specific Python or Julia version, see :ref:`Setting up External Tools`).
+use cases. For more information on how to select a specific Python or Julia version, see :ref:`Setting up Consoles and External Tools`).
 
 .. note:: The **SpineOpt Plugin Toolbar** contains an exporter specification as well as three predefined Tools that make
    use of SpineOpt.jl. **The SpineOpt Plugin is not a requirement to run SpineOpt.jl**, they are provided just for

diff --git a/docs/source/img/executable_tool_spec_dir_runner.png b/docs/source/img/executable_tool_spec_dir_runner.png
diff --git a/docs/source/img/ijulia_missing.png b/docs/source/img/ijulia_missing.png
diff --git a/docs/source/img/ipykernel_missing.png b/docs/source/img/ipykernel_missing.png
diff --git a/docs/source/img/julia_jupyter_console_selected.png b/docs/source/img/julia_jupyter_console_selected.png
diff --git a/docs/source/img/julia_kernel_specification_creator.png b/docs/source/img/julia_kernel_specification_creator.png
diff --git a/docs/source/img/kernel_specs_missing.png b/docs/source/img/kernel_specs_missing.png
diff --git a/docs/source/img/python_jupyter_console_selected.png b/docs/source/img/python_jupyter_console_selected.png
diff --git a/docs/source/img/python_kernel_specification_creator.png b/docs/source/img/python_kernel_specification_creator.png
diff --git a/docs/source/img/settings_tools_default.png b/docs/source/img/settings_tools_default.png
diff --git a/docs/source/img/settings_tools_default_python_git_version.png b/docs/source/img/settings_tools_default_python_git_version.png
diff --git a/docs/source/img/settings_tools_filled_for_spineopt.png b/docs/source/img/settings_tools_filled_for_spineopt.png
diff --git a/docs/source/img/settings_tools_python_installed_version.png b/docs/source/img/settings_tools_python_installed_version.png
diff --git a/docs/source/img/start_jupyter_console_menu_listing.png b/docs/source/img/start_jupyter_console_menu_listing.png
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -12,9 +12,9 @@ Welcome to Spine Toolbox's User Guide!
 computation tasks, such as energy system models.
 
 If you are new to Spine Toolbox, :ref:`Getting Started` section is a good place to start. If you want to run
-`SpineOpt.jl <https://github.com/spine-tools/SpineOpt.jl>`_ using Spine Toolbox, :ref:`How to set up SpineOpt.jl`
+`SpineOpt.jl <https://github.com/spine-tools/SpineOpt.jl>`_ using Spine Toolbox, :ref:`How to Set up SpineOpt.jl`
 provides the step-by-step instructions on how to get started. For information on how to set up Python, Julia, and
-Gams for Spine Toolbox, see :ref:`Setting up External Tools`. Please see :ref:`Settings` chapter for information
+Gams for Spine Toolbox, see :ref:`Setting up Consoles and External Tools`. Please see :ref:`Settings` chapter for information
 on user customizable Spine Toolbox settings. If you need help in understanding the terms we use throughout the app
 and this User Guide, please check the :ref:`Terminology` section. If you want to contribute to this project,
 please see the :ref:`Contribution Guide`. The last section contains the complete code reference of Spine Toolbox.
@@ -23,6 +23,7 @@ please see the :ref:`Contribution Guide`. The last section contains the complete
    :maxdepth: 1
    :caption: Contents:
 
+   whats_new
    getting_started
    how_to_run_spineopt
    setting_up
@@ -31,9 +32,8 @@ please see the :ref:`Contribution Guide`. The last section contains the complete
    links
    tool_specification_editor
    executing_projects
-   execution_modes
    settings
-   Spine database editor <spine_db_editor/index>
+   Spine Database Editor <spine_db_editor/index>
    plotting
    parameter_value_editor
    metadata_description

diff --git a/docs/source/metadata_description.rst b/docs/source/metadata_description.rst
@@ -1,7 +1,7 @@
 .. _Metadata description:
 
 **************************
-Spine metadata description
+Spine Metadata Description
 **************************
 
 This is the metadata description for Spine, edited from `<https://frictionlessdata.io/specs/data-package/>`_.

diff --git a/docs/source/parameter_value_editor.rst b/docs/source/parameter_value_editor.rst
@@ -1,8 +1,7 @@
 ..  Parameter value editor
-    Created: 15.8.2019
 
 **********************
-Parameter value editor
+Parameter Value Editor
 **********************
 
 Parameter value editor is used to edit object and relationship parameter values

diff --git a/docs/source/plotting.rst b/docs/source/plotting.rst
@@ -1,5 +1,4 @@
 ..  Plotting
-    Created: 15.8.2019
 
 Plotting
 ========

diff --git a/docs/source/project_item_development.rst b/docs/source/project_item_development.rst
@@ -1,6 +1,6 @@
 .. _Project item development:
 
-Project item development
+Project Item Development
 ========================
 
 This document discusses the basics of :ref:`project item<Project Items>` development: