diff --git a/docs/source/contribution_guide.rst b/docs/source/contribution_guide.rst index e29452b03..d051a2fdf 100644 --- a/docs/source/contribution_guide.rst +++ b/docs/source/contribution_guide.rst @@ -1,5 +1,4 @@ .. 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/ @@ -7,9 +6,9 @@ .. _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 index d88ad253e..afc5ddb78 100644 --- 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 index 30623ff9d..ffc2cf769 100644 --- 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 deleted file mode 100644 index a2a207c15..000000000 --- a/docs/source/execution_modes.rst +++ /dev/null @@ -1,185 +0,0 @@ -.. How to set up shell or Jupyter Console execution model. - Created 4.6.2021 - -.. |browse| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg - :width: 16 -.. |play| image:: ../../spinetoolbox/ui/resources/menu_icons/play-circle-solid.svg - :width: 16 -.. |stop| image:: ../../spinetoolbox/ui/resources/menu_icons/stop-circle-regular.svg - :width: 16 - -.. _Execution Modes: - -*************** -Execution Modes -*************** - -Python and Julia Tools can be executed in either an embedded basic console or a Jupyter Console. GAMS Tools -are only executed in the shell. Executable tools are a shell or by running the executable file straight. - -Python -****** - -Under the **Tools** page in **File -> Settings...**, you can set the default console for new Python Tool specifications -as either a Basic Console or a Jupyter Console. In the Tool Specification Editor, Tool specification specific selections -can be made overriding the default settings. - -Basic Console -------------- - -If Basic Console is selected (it is by default) Tools are executed in the **Console** dock widget on a basic console. -You can set the default Python interpreter in the settings and item specific interpreters in the -Tool's specification editor. - -Jupyter Console ---------------- -Jupyter Console will also appear in the **Console** dock widget. -If you want to use a Jupyter Console as the default, check the *Jupyter Console* check box. -There is an extra step involved since -the Jupyter Console requires a couple of extra packages (*ipykernel* and its dependencies) to be -installed on the selected Python. In addition, kernel specifications for the selected Python needs to be -installed beforehand. **Spine Toolbox can install these for you**, from the **Python Kernel Specification Creator** widget that -you can open from the **Tools** page in **File -> Settings...** by clicking the **Make Python Kernel** button. - -.. note:: - You can install Python kernel specifications manually and Spine Toolbox will find them. You can select the kernel - spec used in the Jupyter Console from the drop-down menu *Select Python kernel...*. - -.. 1. Go to ``_ and download the Python you want - 2. Run the Python installer and follow instructions - 3. Either let the installer put Python in your PATH or memorize the path where you installed it - (e.g. `C:\\Python38`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Python is now in your PATH, you can leave the Python interpreter line edit blank. - Or you can set the Python interpreter explicitly by setting it to e.g. `C:\\Python38\\python.exe` - by using the |browse| button. - 7. Check the `Use embedded Python Console` check box - 8. Create a project with a Tool and a Python Tool specification (See :ref:`Getting Started`) - 9. Press play to execute the project (See :ref:`Executing Projects`) - 10. You will see a question box - -.. .. image:: img/ipykernel_missing.png - :align: center - -.. When you click on the *Install ipykernel* button, you can see the progress of the - operation in Process Log. The following packages will be installed on your selected Python.:: - -.. backcall, colorama, decorator, ipykernel, ipython, ipython-genutils, jedi, jupyter-client, - jupyter-core, parso, pickleshare, prompt-toolkit, pygments, python-dateutil, pywin32, pyzmq, six, - tornado, traitlets, wcwidth - -.. When this operation finishes successfully, you will see another guestion box. - -.. .. image:: img/kernel_specs_missing.png - :align: center - -.. Clicking on *Install specifications* button starts installing the kernel specs for the selected Python. - On the tested system, this creates a new kernel into directory - `C:\\Users\\ttepsa\\AppData\\Roaming\\jupyter\\kernels\\Python-3.8`, which contains the `kernel.json` file - required by the embedded Python Console (which is actually a jupyter qtconsole) - -.. 11. After the kernel specs have been installed, executing your Tool project item starts in the - Python Console immediately. You can see the executed command and the Tool output in the Python - Console. - -.. .. note:: - If you want to set up your Python environment ready for Python Console manually, the following - commands are executed by Spine Toolbox under the hood - -.. This installs all required packages:: - -.. python -m pip install ipykernel - -.. And this installs the kernel specifications:: - -.. python -m ipykernel install --user --name python-3.8 --display-name Python3.8 - - -Julia -***** - -As with Python, default console type can be selected in the settings and Julia kernels can also be created by pressing -**Make Julia Kernel** -button. In addition a default project can be selected for Julia Tool specifications. - -Basic Console -------------- -On **Tools** page in **File -> Settings...**, check the **Basic Console** radiobutton. -This is the default execution mode for Julia Tools. - -.. 1. Go to ``_ and download the Julia you want - 2. Run the Julia installer and follow instructions - 3. Either let the installer put Julia in your PATH or memorize the path where you installed it - (e.g. `C:\\Julia-1.2.0`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Julia is now in your PATH, you can leave the Julia executable line edit blank. - Or you can set the Julia executable explicitly by setting it to e.g. `C:\\Julia.1.2.0\\bin\\julia.exe` - by using the |browse| button. - 7. Uncheck the `Use embedded Julia Console` check box - 8. Create a project with a Tool and a Julia Tool specification (See :ref:`Getting Started`) - 9. Press |play| to execute the project (See :ref:`Executing Projects`) - 10. Executing your Tool project item starts. You can see the output (stdout and stderr) in the - Process Log. - -Jupyter Console ---------------- - -Like the Python Console, the Jupyter Console with Julia requires some extra setting up. A couple of -additional packages (`IJulia`, etc.) are required to be installed and built. **Spine Toolbox can set this up for you -automatically**. Just click the **Make Julia Kernel** button after selecting the **Jupyter Console** -radiobutton. - -.. note:: - You can install Julia kernel specifications manually and Spine Toolbox will find them. You can select the kernel - spec used in the Jupyter Console from the drop-down menu *Select Julia kernel...*. - -.. 1. Go to ``_ and download the Julia you want - 2. Run the Julia installer and follow instructions - 3. Either let the installer put Julia in your PATH or memorize the path where you installed it - (e.g. `C:\\Julia-1.2.0`) - 4. Start Spine Toolbox - 5. Go to File -> Settings (or press F1) and click the Tools tab open - 6. If the installed Julia is now in your PATH, you can leave the Julia executable line edit blank. - Or you can set the Julia executable explicitly by setting it to e.g. `C:\\Julia.1.2.0\\bin\\julia.exe` - by using the |browse| button. - 7. Check the `Use embedded Julia Console` check box - 8. Create a project with a Tool and a Julia Tool specification (See :ref:`Getting Started`) - 9. Press |play| to execute the project (See :ref:`Executing Projects`) - 10. You will see a question box - -.. .. image:: img/ijulia_missing.png - :align: center - -.. When you click on the *Allow* button, installing IJulia starts and you can see the progress of the - operation in Process Log. **This may take a few minutes**. - -.. When you see the these messages in the Event Log, the Julia Console is ready to be used.:: - -.. IJulia installation successful. - *** Starting Julia Console *** - -.. 11. After the installation has finished, executing your Julia Tool project item starts in the - Julia Console immediately. You can see the executed command and the Tool output in the Julia - Console. If nothing seems to be happening in the Julia Console. Just click |Stop| button and - then try executing the project again by clicking the |play| button. - -Executable -********** - -With executable Tool types there are two ways to run the executable file: using a shell or without one. - -Using a shell -------------- - -To run an executable with a shell you need to select a shell out of the three available options that is -appropriate for the operating system you are running Spine Toolbox on. Then you can write a command that -runs the executable with the arguments that it needs into the *Command* textbox just like you would on a -normal shell. - -Without a shell ---------------- - -To run an executable file without a shell you can either select the executable file as the main program -file of the Tool and write the possible arguments into *Command line arguments* or select *no shell* and -write the filepath of the executable file followed by it's arguments into the *Command* textbox. -Either way the file is executed independent of a shell and with the provided arguments. diff --git a/docs/source/execution_tests.rst b/docs/source/execution_tests.rst index 016816d2a..38f2ec0c2 100644 --- 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 index 809919445..eb2e73e2d 100644 --- 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 `_ 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 `_. 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 `_, diff --git a/docs/source/how_to_run_spineopt.rst b/docs/source/how_to_run_spineopt.rst index 7ab6a42ee..f03ddf5c9 100644 --- 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 ``_ 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 `_ @@ -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 `_ (takes you to SpineOpt documentation). See also `Tutorials `_ 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 new file mode 100644 index 000000000..d6d6373c0 Binary files /dev/null and b/docs/source/img/executable_tool_spec_dir_runner.png differ diff --git a/docs/source/img/ijulia_missing.png b/docs/source/img/ijulia_missing.png deleted file mode 100644 index 6e60a6001..000000000 Binary files a/docs/source/img/ijulia_missing.png and /dev/null differ diff --git a/docs/source/img/ipykernel_missing.png b/docs/source/img/ipykernel_missing.png deleted file mode 100644 index 763814ab7..000000000 Binary files a/docs/source/img/ipykernel_missing.png and /dev/null differ diff --git a/docs/source/img/julia_jupyter_console_selected.png b/docs/source/img/julia_jupyter_console_selected.png new file mode 100644 index 000000000..163714b1b Binary files /dev/null and b/docs/source/img/julia_jupyter_console_selected.png differ diff --git a/docs/source/img/julia_kernel_specification_creator.png b/docs/source/img/julia_kernel_specification_creator.png new file mode 100644 index 000000000..46f3c095c Binary files /dev/null and b/docs/source/img/julia_kernel_specification_creator.png differ diff --git a/docs/source/img/kernel_specs_missing.png b/docs/source/img/kernel_specs_missing.png deleted file mode 100644 index ef823a53f..000000000 Binary files a/docs/source/img/kernel_specs_missing.png and /dev/null differ diff --git a/docs/source/img/python_jupyter_console_selected.png b/docs/source/img/python_jupyter_console_selected.png new file mode 100644 index 000000000..af3c3b900 Binary files /dev/null and b/docs/source/img/python_jupyter_console_selected.png differ diff --git a/docs/source/img/python_kernel_specification_creator.png b/docs/source/img/python_kernel_specification_creator.png new file mode 100644 index 000000000..914e4b5f2 Binary files /dev/null and b/docs/source/img/python_kernel_specification_creator.png differ diff --git a/docs/source/img/settings_tools_default.png b/docs/source/img/settings_tools_default.png new file mode 100644 index 000000000..c87bf15fb Binary files /dev/null and b/docs/source/img/settings_tools_default.png differ diff --git a/docs/source/img/settings_tools_default_python_git_version.png b/docs/source/img/settings_tools_default_python_git_version.png deleted file mode 100644 index 890bc56ff..000000000 Binary files a/docs/source/img/settings_tools_default_python_git_version.png and /dev/null differ diff --git a/docs/source/img/settings_tools_filled_for_spineopt.png b/docs/source/img/settings_tools_filled_for_spineopt.png deleted file mode 100644 index b125e5e88..000000000 Binary files a/docs/source/img/settings_tools_filled_for_spineopt.png and /dev/null differ diff --git a/docs/source/img/settings_tools_python_installed_version.png b/docs/source/img/settings_tools_python_installed_version.png deleted file mode 100644 index d32ee36bf..000000000 Binary files a/docs/source/img/settings_tools_python_installed_version.png and /dev/null differ diff --git a/docs/source/img/start_jupyter_console_menu_listing.png b/docs/source/img/start_jupyter_console_menu_listing.png new file mode 100644 index 000000000..f286a04de Binary files /dev/null and b/docs/source/img/start_jupyter_console_menu_listing.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index f70720971..ef3611d96 100644 --- 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 `_ using Spine Toolbox, :ref:`How to set up SpineOpt.jl` +`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 Database Editor plotting parameter_value_editor metadata_description diff --git a/docs/source/metadata_description.rst b/docs/source/metadata_description.rst index 9358fc89f..9f3ddae73 100644 --- 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 ``_. diff --git a/docs/source/parameter_value_editor.rst b/docs/source/parameter_value_editor.rst index 3cafa74f0..89e1f9eae 100644 --- 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 index 71272f3d0..3dc587dd1 100644 --- 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 index dcd1029ed..f4dc77a18 100644 --- 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` development: diff --git a/docs/source/setting_up.rst b/docs/source/setting_up.rst index 4b066b1d3..fc77b0ec6 100644 --- a/docs/source/setting_up.rst +++ b/docs/source/setting_up.rst @@ -1,5 +1,4 @@ -.. Setting up External Tools - Created 2.4.2020 +.. Setting up Consoles and External Tools .. |browse| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg :width: 16 @@ -8,101 +7,203 @@ .. |stop| image:: ../../spinetoolbox/ui/resources/menu_icons/stop-circle-regular.svg :width: 16 -.. _Setting up External Tools: +.. _Setting up Consoles and External Tools: -************************* -Setting up External Tools -************************* +************************************** +Setting up Consoles and External Tools +************************************** + +This section describes the options for executing different Python, Julia, Gams, and Executable Tools and how to set +them up. To get started with **SpineOpt.jl**, see :ref:`How to Set up SpineOpt.jl`. See also +:ref:`Executing Projects`. -This section describes the default **Python** used by Spine Toolbox and how to change that. Here you can also find the -instructions on how to set up **Julia** and **Gams** for executing Julia and Gams Tools. To get started with -**SpineOpt.jl**, see :ref:`How to set up SpineOpt.jl`. See also :ref:`Executing Projects` and :ref:`Execution Modes`. .. contents:: :local: +Python and Julia Tools can be executed either in an embedded *Basic Console* or in a *Jupyter Console*. GAMS Tools +are executed in a sub-process. Executable Tools (external programs) are executed in a shell or by running the +executable file straight. You can also make a Tool that executes a shell command by creating an *Executable* Tool +Spec in **Tool Specification Editor**, entering the shell command to the *Command* line edit and then selecting the +Shell for this Tool. + +Basic Consoles +-------------- +Basic Console appears to the **Console** dock widget in the main window when you execute (|play|) a project +containing either a Python or a Julia Tool with Basic Console selected. + Python ****** -No set up required! Python Tools are executed using the **default Python**, which **depends on how you installed Spine Toolbox.** The -installation options are: - -1. Using a single-file **installation bundle** (e.g. *spine-toolbox-0.6.0-final.2-x64.exe* or newer). You can - find this file and all releases from - `Spine Toolbox releases `_. - The installation bundles are only available for Windows at the moment. -2. Cloning Spine Toolbox Git repository from ``_. Checkout branch - **release-0.6** or **master** and run `pip install -r requirements.txt` in the repo root. - -.. tip:: You can always see the current Python configured for Spine Toolbox from the `Tools` page in - `File->Settings...`. - -Default Python for Spine Toolbox installed using an installation bundle ------------------------------------------------------------------------ -The default Python is the **Python in your PATH** environment variable. **If Python is not in your PATH**, the -default Python is an 'embedded' Python that is shipped with the installation bundle. The 'embedded' Python is -located in *\\tools\\python.exe*, where ** is *C:\\Program Files\\Spine Toolbox* if you -installed Spine Toolbox to the default directory for all users. - -.. important:: If you want access to `spinedb_api` package from Tools and Consoles in Spine Toolbox, bear in mind - that the version of `spinedb_api` must be compatible with the version of Spine Toolbox you are using! Spine - Toolbox v0.6.0 is shipped with `spinedb_api` v0.12.1. If you want to use the Python in your PATH, **you must install - the correct version of spinedb_api for this Python manually**. The correct version in this case is in the - `release-0.12` branch of `spinedb_api` git repo - (https://github.com/spine-tools/Spine-Database-API/tree/release-0.12). - **To avoid this additional step, it is recommended** that you use the 'embedded' Python interpreter that is shipped - with the application. You can set up this Python for Spine Toolbox by opening the `Tools` page of - `File->Settings...` and replacing the path of the Python Interpreter with *\\tools\\python.exe*. - **The 'embedded' Python interpreter has access to `spinedb_api` that is shipped with the application.** - -Here are the recommended settings - -.. image:: img/settings_tools_python_installed_version.png +Executing a Python Tool in the Basic Console requires no set up. Simply create a *Python* Tool Spec in +**Tool Specification Editor** and select the Basic Console radio button. The default Python interpreter used +in launching the Console is the same Python that was used in launching Spine Toolbox. You can also select another +Python by changing the Python interpreter line edit. Remember to save the new Tool Spec when closing the **Tool +Spec. Editor**. Then drag the Python Tool Spec into the **Design View**, and press |play| to execute it. + +.. note:: The Python settings on the *Tools* page in **File -> Settings** are the *default* settings for new Python + Tool Specs. You can select a different Python executable for each Python Tool Spec separately using the + **Tool Specification Editor**. + +Julia +***** +To execute Julia Tools in the Basic Console, first install Julia (v1.6 or later) +`from here `_ and add `/bin` to your PATH environment variable +(if not done automatically by the installer). Then go to the *Tools* page in **File -> Settings** and make sure that +the Basic Console radio button is selected in the Julia group. If Julia is in your PATH, the Julia executable line +edit should show the path as (grey) placeholder text. If you want to use another Julia on your system, you can change +the path in the line edit. You can also set a Julia Project below the Julia executable line edit. + +.. note:: The Julia settings are *global* application settings. All Julia Tools are executed with the settings + selected on the *Tools* page in **File -> Settings**. In upcoming versions, the Julia settings will be consistent + with the Python settings, in a way that you can select a specific Julia executable and Julia project for each + Julia Tool Spec separately. + +Jupyter Consoles +---------------- +Jupyter Console appears to the **Console** dock widget in the main window when you execute (|play|) a project +containing either a Python or a Julia Tool with the *Jupyter Console* selected. The Jupyter Console +requires a Jupyter kernel to be installed on your system. Kernels are programming language specific processes +that run independently and interact with the Jupyter Applications and their user interfaces. + +Python +****** +Select *Jupyter Console* radio button in **File -> Settings**. You also need to select the Python kernel you +wish to use from the *Select Python kernel...* combo box. If this list is empty, you need to install the kernel specs +on your system. You can either do this manually or click the **Make Python Kernel** button. Clicking the button opens +a **Python Kernel Specification Creator** window, that first installs the **ipykernel** package (if missing) for +the Python that is currently selected in the Python interpreter line edit (the kernel specs will be created +for `C:/Python39/python.exe` in the picture below). You can make kernel specs for other Pythons and virtual +environments (venv) by changing the Python interpreter line edit path to point to another Python. Please see +specific instructions for creating kernel specs for Conda environments below. + +.. image:: img/python_jupyter_console_selected.png :align: center -Default Python for Spine Toolbox installed using Git ----------------------------------------------------- -The default Python is the **Python that was used in launching the application** (i.e. *sys.executable*). -When you start the app for the first time (or if you clear the path), the path to the default Python is -shown as placeholder (gray) text in the line edit like this: +Once the **ipykernel** package is installed, the wizard runs the **ipykernel** install command, which creates the +kernel specs directory on your system. You can quickly open the kernel spec directory from the +**Select Python Kernel...** combo box's context-menu (mouse right-click menu). Once the process finishes, +click Close, and the newly created kernel spec (*python39* in this case) should be selected automatically. +Click *Ok* to close the **Settings** widget and to save your selections. -.. image:: img/settings_tools_default_python_git_version.png +.. image:: img/python_kernel_specification_creator.png :align: center -The default Python has access to the `spinedb_api` version that was installed with the application (the one in -in \\lib\\site-packages\\spinedb_api). +If something went wrong, or if you want to remake the kernel specs, you can remove the kernel spec directory from +your system, try the **Make Python Kernel** button again, or install the kernel specs manually. + +If you want to install the Python kernel specs manually, these are the commands that you need to run. + +To install **ipykernel** and it's dependencies, run:: + + python -m pip install ipykernel -Changing the default Python ---------------------------- -If you want to use another Python than the default, you can use existing Pythons in your system or you can -download additional Pythons from ``_. You can change the default Python -on the `Tools` page of `File->Settings...` by clicking the |browse| button and selecting the Python interpreter -(`python.exe` on Windows) you want. You can use **any Python in your system**. +And to install the kernel specs run:: + + python -m ipykernel install --user --name python39 --display-name python39_spinetoolbox + +Make sure to use the ``--user`` argument to make sure that the kernel specs are discoverable by Spine Toolbox. + +.. note:: + Clicking **Make Python Kernel** button when the kernel specs have already been installed, does NOT open the + **Python Kernel Specification Creator**, but simply selects the Python kernel automatically. .. note:: Executing Python Tools using the Jupyter Console supports Python versions from 2.7 all the way to newest one. - Executing Python Tools **without** using the Jupyter Console supports even earlier Pythons than 2.7. - You can start Spine Toolbox only with Python 3.7 or with 3.8, but you can set up a Jupyter Console in - Spine Toolbox that uses e.g. Python 2.7. This means, that if you still have some old Python 2.7 scripts - lying around, you can incorporate those into a Spine Toolbox project workflow and execute them without - modifications. + This means, that if you still have some old Python 2.7 scripts lying around, you can incorporate those into + a Spine Toolbox project workflow and execute them without modifications. .. important:: If you want to have access to `spinedb_api`, you need to install it manually for the Python you select here. Julia ***** -Executing Julia Tools in Spine Toolbox requires that Julia is installed on your system. Julia downloads are -available from ``_. You can see the current Julia on the `Tools` page in -`File->Settings...`. The **default Julia is the Julia in your PATH** environment variable. Setting some other -Julia to the line edit overrides the Julia in PATH. If you want to use 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 line edit (the one that says *Using Julia default project* when empty). +To use the Jupyter Console with Julia Tools, go to the *Tools* page in **File -> Settings** and select the +Jupyter Console radio button like in the picture below. + +.. image:: img/julia_jupyter_console_selected.png + :align: center + +Like with Python, you need to select an existing Julia kernel for the Julia Jupyter Console, or create one +either manually, or by clicking the **Make Julia Kernel** button. + +.. image:: img/julia_kernel_specification_creator.png + :align: center + +Clicking the button opens **Julia Kernel Specification Creator** window, that first installs the **IJulia** package +(if missing) for the Julia and Julia project that are currently selected in the Julia executable and Julia Project +line edits (the kernel specs will be created for the default project of `C:/Julia-1.9.0/bin/julia.exe` in the +picture above). + +If something went wrong, or if you want to remake the kernel specs, you can remove the kernel spec directory from +your system, try the **Make Julia Kernel** button again, or install the kernel specs manually. + +If you want to install the Julia kernel specs manually, these are the commands that you need to run. + +To install **IJulia** and it's dependencies, open Julia REPL with the project you want and run:: -If you are trying to execute Julia Tools and you see an error message in Event Log complaining about not finding -Julia, you either don't have a Julia installation in your PATH, or the Julia path in Settings is invalid. + using Pkg + Pkg.add("IJulia") + +Rebuild IJulia:: + + Pkg.build("IJulia") + +And to install the kernel specs run:: + + using IJulia + installkernel("julia", --project="my_project") + +.. note:: + Clicking **Make Julia Kernel** button when the kernel specs have already been installed, does NOT open the + **Julia Kernel Specification Creator**, but simply selects a Julia kernel that matches the selected Julia + executable and Julia Project. If a kernel spec matching the Julia executable is found but the Julia project is + different, a warning window appears, saying that Julia kernel spec may be overwritten if you continue. + +Conda +***** +You also have the option of running Python Tools in a Conda environment. All you need to do is the following. + +1. Open Anaconda Prompt and make a new Conda environment:: + + conda create -n test python=3.10 + +2. Activate the environment:: + + conda activate test + +3. Install **ipykernel**:: + + pip install ipykernel + +4. Back in Spine Toolbox, add path to Conda executable on the *Tools* page in **File -> Settings**. + +That's it! Now, in Spine Toolbox main window, open the **Consoles -> Start Jupyter Console** menu, wait a second, +and the new kernel should appear in the list. In this case, the new kernel name is *conda-env-.conda-test-py*. +This autogenerated name will most likely change to something more readable in the future. You can use Conda Python +kernels just like regular Python kernels, i.e. select one of them as the default kernel in the +**File -> Settings** widget or select them for individual Python Tool Specs in **Tool Specification Editor** directly. + +Detached Consoles +***************** +You can open 'detached' Jupyter Consoles from the main window menu **Consoles -> Start Jupyter Console**. The menu +is populated dynamically with every Jupyter kernel that Spine Toolbox is able to find on your system. 'Detached' +here means that the Consoles are not bound to any Tool. These Consoles are mostly useful e.g. for +checking that the kernel has access to the correct packages, debugging, small coding, testing, etc. These may be +especially useful for checking that everything works before running a full workflow that may take hours to finish. + +Officially, Spine Toolbox only supports Python and Julia Jupyter kernels but it's possible that other kernels can +be accessed in a Detached Console as well. For example, if you install a javascript kernel on your system, you can +open a Detached Console for it, but this does not mean that Spine Toolbox projects should support Javascript. However, +if there's interest and legitimate use cases for other kernels, we may build support for them in future releases. + +.. image:: img/start_jupyter_console_menu_listing.png + :align: center + +If interested, you can `read more on Jupyter kernels `_ . +There you can also find a `list of available kernels `_. GAMS -**** +---- Executing Gams Tools or needing to use the GDX file format requires an installation of Gams on your system. You can download Gams from ``_. @@ -110,9 +211,26 @@ You can download Gams from ``_. .. important:: The bitness (32 or 64bit) of Gams has to match the bitness of the Python interpreter. -The default Gams is the Gams defined under ``gams.location`` in Windows registry or in your PATH environment variable. -You can see the one that is currently in use from the `Tools` page in `File->Settings...`. -The placeholder text shows the default Gams if found. -You can also override the default Gams by setting some other gams.exe path to the line edit -(e.g. `C:\\GAMS\\win64\\28.2\\gams.exe`). +The default Gams is the Gams defined under ``gams.location`` in Windows registry or in your PATH environment +variable. You can see the one that is currently in use from the *Tools* page in **File -> Settings**. The +placeholder text shows the default Gams if found. You can also override the default Gams by setting some other +gams executable path to the line edit. + +Executable +---------- +Executable Tool Spec types can be used to execute virtually any program as part of a Spine Toolbox workflow. They +also provide the possibility to run Shell commands as part the workflow. To run an executable with a shell you +need to select a shell out of the three available options that is appropriate for your operating system. +Then you can write a command that runs the executable with the arguments that it needs into the *Command* +line edit just like you would on a normal shell. +To run an executable file without a shell you can either select the executable file as the main program +file of the Tool and write the possible arguments into *Command line arguments* or select *no shell* and +write the filepath of the executable file followed by it's arguments into the *Command* textbox. +Either way the file is executed independent of a shell and with the provided arguments. + +To run a Shell command, just type the command into the *command* line edit and select the appropriate Shell from the +list. Picture below depicts an Executable Tool Spec that runs *dir* in in cmd.exe. + +.. image:: img/executable_tool_spec_dir_runner.png + :align: center diff --git a/docs/source/settings.rst b/docs/source/settings.rst index c78eeaa78..678ee256f 100644 --- a/docs/source/settings.rst +++ b/docs/source/settings.rst @@ -1,5 +1,7 @@ .. Settings form documentation - Created 14.1.2019 + +.. |open-folder| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-solid.svg + :width: 16 .. _Settings: @@ -7,16 +9,17 @@ Settings ******** -You can open Spine Toolbox settings from the main window menu `File->Settings...`, or by +You can open Spine Toolbox settings from the main window menu **File -> Settings...**, or by pressing **Ctrl+,**. Settings are categorized into five tabs; *General*, *Tools*, *Db editor*, *Spec. editors* and *Engine*. -In addition to application settings, each Project item has user adjustable -properties (See :ref:`Project Items`) +In addition to application settings, each project item has user adjustable +properties (See :ref:`Project Items`). See also :ref:`Setting up Consoles and External Tools` +for more information on how to set up Consoles and external Tools. .. contents:: :local: -General settings +General Settings ---------------- .. image:: img/settings_general.png @@ -32,7 +35,7 @@ Settings in the **Main** group: - **Delete data when project item is removed from project** Check this box to delete project item's data when a project item is removed from project. This means that the *project item directory* and its contents will be deleted from your hard drive. You can find the project item directories from the - ``/.spinetoolbox/items/`` directory, where ```` is your current project directory. + `/.spinetoolbox/items/` directory, where `` is your current project directory. - **Open previous project at startup** If checked, application opens the project at startup that was open the last time the application was shut down. If left unchecked, application starts without a @@ -45,7 +48,7 @@ Settings in the **Main** group: when the application exits. - **Work directory** Directory where processing the Tool takes place. Default place (if left empty) is - the ``/work`` subdirectory of Spine Toolbox install directory. You can change this directory. + the `/work` subdirectory of Spine Toolbox install directory. You can change this directory. Make sure to clean up the directory every now and then. Settings in the **UI** group: @@ -55,44 +58,109 @@ Settings in the **UI** group: - **Color properties widgets** Check this box to make the background of Project item properties more colorful. -- **Curved links** Controls the look of the arrows on Design View. +- **Curved links** Controls the look of the arrows on **Design View**. - **Drag to draw links** When checked, the mouse button needs to be pressed while drawing links between project items. If unchecked, single clicks at link source and destination items suffices. - **Prevent items from overlapping** When checked, other project items can be pushed away when - moving an item around the Design view. If left unchecked, items can be piled on top of each other. + moving an item around the **Design view**. If left unchecked, items can be piled on top of each other. - **Rounded items** Check this box to round the corners of otherwise rectangular project items. -- **Show date and time in Event Log messages** If checked, every Event Log message is prepended with +- **Show date and time in Event Log messages** If checked, every **Event Log** message is prepended with a date and time 'tag'. -- **Smooth zoom** Controls the way zooming (by using the mouse wheel) behaves in Design View and in - Spine database editor. Controls if the zoom in/out is continuous or discrete. On older computers, +- **Smooth zoom** Controls the way zooming (by using the mouse wheel) behaves in **Design View** and in + **Spine DB Editor**. Controls if the zoom in/out is continuous or discrete. On older computers, smooth zoom is not recommended because it may be slower. -- **Background** Has some pattern options for the background of the Design view. +- **Background** Has some pattern options for the background of the **Design View**. Clicking on the square next to 'Color' let's you choose the pattern's color. -- **Link flash speed** This slider controls the speed of the link animation on Design - View when execution is ongoing. +- **Link flash speed** This slider controls the speed of the link animation on **Design + View** when execution is ongoing. -Tools settings +Tools Settings -------------- -The Tool settings tab contains settings for external tools. -See :ref:`Setting up External Tools` for more information and examples. +The Tools tab contains settings for external tools. + +.. image:: img/settings_tools_default.png + :align: center + +Settings in the **GAMS** group: + +- **GAMS executable** Set the path to GAMS executable you want to use when executing GAMS tools. If you have GAMS in + your PATH environment variable, it will be automatically used. You can also choose another GAMS by clicking the + |open-folder| button. + +Settings in the **Julia** group: + +Choose the settings on how Julia Tools are executed. + +- **Basic Console** When selected, Julia Tools will be executed in a custom interactive Julia REPL. + +- **Julia executable** Set the path to a Julia Executable used in launching the Basic Console. If Julia is in PATH + this will be autofilled, but you can also choose another Julia executable. + +- **Julia project** Set the Julia project you want to activate in the Basic Console. + +- **Jupyter Console** Choosing this option runs Julia Tools in a custom Jupyter QtConsole embedded into Spine Toolbox. + +- **Select Julia kernel... drop-dowm menu** Select the kernel you want to launch in Jupyter Console. + +- **Make Julia Kernel** clicking this button makes a new kernel based on the selected *Julia executable*, and *Julia + project*. The progress of the operation is shown in another dialog. Installing a Julia kernel requires the **IJulia** + package which will be installed to the selected *Julia project*. After **IJulia** has been installed, the kernel is + installed. This process can take a couple of minutes to finish. + +- **Install Julia** Installs the latest Julia on your system using the **jill** package. + +- **Add/Update SpineOpt** Installs the latest compatible **SpineOpt** to the selected Julia project. If the selected + *Julia project* already has SpineOpt, it is upgraded if there's a new version available. + +.. note:: These Julia settings are *global* application settings. All Julia Tools are executed with the settings + selected here. + +Settings in the **Python** group: + +Choose the settings on how Python Tools are executed. + +- **Basic Console** When selected, Python Tools will be executed in a custom interactive Python REPL. + +- **Python executable** Set the path to a Python Executable used in launching the Basic Console. The default option + (if the line edit is blank) is the Python executable that was used in launching Spine Toolbox. + +- **Jupyter Console** Choosing this option runs Python Tools in a custom Jupyter QtConsole embedded into Spine + Toolbox. + +- **Select Python kernel... drop-dowm menu** Select the kernel you want to launch in Jupyter Console. + +- **Make Python Kernel** clicking this button makes a new kernel based on the selected *Python executable*. The + progress of the operation is shown in another dialog. Installing a Python kernel (actually IPython kernel) + requires the **ipykernel** package which will be installed to the selected *Python executables*. After + **ipykernel** has been installed, the kernel is installed. This process can take a couple of minutes to finish. + +.. note:: These Python settings are just the default settings *for new Python Tool Specs*. You can select a + specific Python kernel for each Python Tool Spec separately using the **Tool Specification Editor**. + +Settings in the **Conda** group: + +- **Miniconda executable** If you want to run Python Tools in a Conda environment, you can set the path + to your Conda executable here. + +See :ref:`Setting up Consoles and External Tools` for more information and examples. -Database editor settings ------------------------- +Db editor Settings +------------------ .. image:: img/settings_db_editor.png :align: center -This tab contains settings for the Database editor. -The same settings can be accessed directly from the Database editor itself. +This tab contains settings for the Spine Database editor. The same settings can be accessed directly +from the Database editor itself. - **Commit session before closing** This checkbox controls what happens when you close a database editor which has uncommitted changes. When this is unchecked, all changes are discarded without @@ -126,8 +194,8 @@ The same settings can be accessed directly from the Database editor itself. that are open on the same table into a single graph if they contains common object nodes. If unchecked, a separate graph will be drawn for each database. -Specification editor settings ------------------------------ +Spec. editor Settings +--------------------- .. image:: img/settings_specification_editors.png :align: center diff --git a/docs/source/spine_db_editor/index.rst b/docs/source/spine_db_editor/index.rst index 6672cd533..fdad1e7f2 100644 --- a/docs/source/spine_db_editor/index.rst +++ b/docs/source/spine_db_editor/index.rst @@ -1,7 +1,7 @@ .. _Spine db editor: -Welcome to Spine database editor's User Guide! +Welcome to Spine Database Editor's User Guide! ============================================== Spine database editor is a dedicated component of Spine Toolbox, diff --git a/docs/source/tool_specification_editor.rst b/docs/source/tool_specification_editor.rst index 0e9a614c1..128c2d370 100644 --- a/docs/source/tool_specification_editor.rst +++ b/docs/source/tool_specification_editor.rst @@ -1,5 +1,4 @@ .. Tool specification editor documentation - Created 15.1.2019 .. |folder_open| image:: ../../spinetoolbox/ui/resources/menu_icons/folder-open-regular.svg :width: 16 @@ -15,7 +14,7 @@ .. _Tool specification editor: ************************* -Tool specification editor +Tool Specification Editor ************************* This section describes how to make a new Tool specification and how to edit existing Tool specifications. @@ -89,8 +88,8 @@ The Tool specification file is a text file in JSON format and has an extension * You can change the location by pressing [change]. Also, you need to save your project for the specification to stick. -.. tip:: Only *name*, *type*, and *main program file* fields are required to make a Tool specification. The other - fields are optional. +.. tip:: Only *name*, *type*, and either *main program file* or *command* fields are required to make a Tool + specification. The other fields are optional. Here is a minimal Tool specification for a Julia script *script.jl* diff --git a/docs/source/ui_guidelines.rst b/docs/source/ui_guidelines.rst index 9b871cd86..7aff3e2a7 100644 --- a/docs/source/ui_guidelines.rst +++ b/docs/source/ui_guidelines.rst @@ -1,6 +1,6 @@ .. _UI guidelines: -UI guidelines +UI Guidelines ============= Keyboard shortcuts diff --git a/docs/source/unit_testing_guidelines.rst b/docs/source/unit_testing_guidelines.rst index 2ac3cb654..56441e966 100644 --- a/docs/source/unit_testing_guidelines.rst +++ b/docs/source/unit_testing_guidelines.rst @@ -1,6 +1,6 @@ .. _Unit testing guidelines: -Unit testing guidelines +Unit Testing Guidelines ======================= Test modules, directories diff --git a/docs/source/whats_new.rst b/docs/source/whats_new.rst new file mode 100644 index 000000000..e80bb58e4 --- /dev/null +++ b/docs/source/whats_new.rst @@ -0,0 +1,10 @@ +.. _Whats new: + +*********** +What's New? +*********** + +Here's the Changelog for Spine Toolbox. + +.. include:: ../../CHANGELOG.md + :literal: diff --git a/spinetoolbox/fetch_parent.py b/spinetoolbox/fetch_parent.py index 19fab9253..e7641f107 100644 --- a/spinetoolbox/fetch_parent.py +++ b/spinetoolbox/fetch_parent.py @@ -22,7 +22,7 @@ class FetchParent(QObject): Attrs: fetch_token (int or None) will_have_children (bool or None): Whether this parent will have children if fetched. - None means we don't know yet. Set to a boolean value whenever we find out. + None means we don't know yet. Set to a boolean value whenever we find out. """ _changes_pending = Signal() @@ -31,9 +31,9 @@ def __init__(self, owner=None, chunk_size=1000): """ Args: owner (object): somebody who owns this FetchParent. If it's a QObject instance, then this FetchParent - becomes obsolete whenever the owner is destroyed + becomes obsolete whenever the owner is destroyed chunk_size (int or None): the number of items this parent should be happy with fetching at a time. - If None, then no limit is imposed and the parent should fetch the entire contents of the DB. + If None, then no limit is imposed and the parent should fetch the entire contents of the DB. """ super().__init__() self._timer = QTimer() diff --git a/spinetoolbox/mvcmodels/map_model.py b/spinetoolbox/mvcmodels/map_model.py index 3983d586e..04437bc78 100644 --- a/spinetoolbox/mvcmodels/map_model.py +++ b/spinetoolbox/mvcmodels/map_model.py @@ -564,7 +564,7 @@ def _apply_index_names(map_value, index_names): def _numpy_string_to_python_strings(rows): - """Converts instances of numpy.str_ to regular Python strings. + """Converts instances of ``numpy.str_`` to regular Python strings. Args: rows (list of list): table rows diff --git a/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py b/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py index 7b2da2d57..7e5f2495e 100644 --- a/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py +++ b/spinetoolbox/spine_db_editor/mvcmodels/alternative_model.py @@ -63,7 +63,7 @@ def paste_alternative_mime_data(self, mime_data, database_item): Args: mime_data (QMimeData): mime data - database_item (DBItem): target database item + database_item (alternative_item.DBItem): target database item """ alternative_data = pickle.loads(mime_data.data(mime_types.ALTERNATIVE_DATA)) names_to_descriptions = {}