Bring documentation up-to-date

[soininen]

Toolbox documentation is outdated at places and missing information. Lets improve it!

General consistency

• Keyboard shortcuts in bold, a plus sign separating modifiers, letters in uppercase: Ctrl+Alt+Shift+A.
• UI element names in bold: Purge, Design View
• Menu item "paths" separated by ->: View -> Dock Widgets
• Project item names as normal text: Importer, Data Connection
• File names as literal text with *NIX style separators: project.json, <project root>/.spinetoolbox/items/
• Screenshots taken with default factory settings; no curved links, rounded items etc. unless for demonstration purposes
• Headers capitalized: Executing Project, Importing and Exporting Data

Getting Started

• Follow the #instructions on how to set up a project. Make sure the instructions still work and are up-to-date.
• Update outdated screenshots.
• Make sure all links work.

How to Set up SpineOpt.jl

• Follow the instructions on how to set up a SpineOpt. Make sure the instructions still work and are up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Tutorials

SpineOpt tutorials have been moved to SpineOpt documentation.

• Add links to SpineOpt tutorials into Getting Started section
• Remove this section
• Close (don't merge) Major improvements to case study a5 description. #1291

Setting up External Tools Setting up Consoles and External Tools

Note that the Settings/Tool Settings section links here so this section should serve as documentation for the Tools tab in Settings window as well.

• Update text and bring in relevant things from Execution Modes section
• Update outdated screenshots.
• Make sure all links work.

Main Window

• Update the text.
• Update outdated screenshots.
• Make sure all links work.

Project Items

Data connection nowadays supports generic URL references, e.g. to remote non-Spine databases.

There is probably other things that should be mention here for items that don't have a dedicated page (at least Tool, Importer and Exporter have one).

• Make sure the item descriptions are up-to-date.
• Make sure all links work.

Links

• Create new section for links and their properties

Tool Specification Editor

• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.
• Add a note that instance-specific command line arguments can be modified in Tool properties tab
• Make sure information is not scattered between this section and Execution Modes and Setting up External tools -sections

Executing Projects

We need to explain scenario and tool filters as well as how Engine parallelizes the workflow. Could be here or in a separate section.

• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Execution Modes

"Executable" execution mode has nowadays options which shell (or no shell) to use. These should be explained here.

Tool Specification Editor section should probably link here.

• Add still relevant things to Setting up Consoles and External Tools and remove section

Note This section was basically duplicating the things in Setting up Consoles and External Tools.

Settings

This section has been recently updated.

• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Spine Database Editor

See #2306

Plotting

In the long run, this section should be incorporated into Spine Database Editor documentation

• Add instructions on how to view the plot data from plot windows (Right click on plot, select Show plot data... or Copy plot data).
• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Parameter Value Editor

In the long run, this section should be incorporated into Spine Database Editor documentation

• Add instructions on how to change Index names.
• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Importing and Exporting Data

Some topics to add here (there is probably a lot more missing in the docs):

• Importers use specifications as well.
• Importers have a file-less mode.
• Importers have nowadays a Filter column.
• How to set column/row type for multiple rows at once
• How Exporter's Output file/label works
• How to set up export to a remote database (not only sqlite is supported!)
• Exporter's Compact button
• Make sure the text is up-to-date.
• Update outdated screenshots.
• Make sure all links work.

Spine Engine Server

• Make sure the text is up-to-date.
• Make sure all links work.

Terminology

Any new terms that should be added here?

• Make sure the text is up-to-date.

Dependencies

Do we really need this page?

• Remove page

Contribution Guide for Spine Toolbox

• Make sure all links work.

Developer Documentation

• Update Publishing to PyPI -section
• Make sure all links work.

Other Things that need to be added

• Specifications: general info about specification files, how to add one from file, how to create one, how to save one under different name.
• Write order index: what it is, how to set up sane write orders with Importers, Mergers.
• Plugins: installing, updating, removing, using.
• Purging: from link arrows, from Data Store properties tab, from Database editor.
• Vacuuming: from Data Store properties tab, from Database editor.
• Undo/redo in different windows.
• Datapackages
• In-memory databases
• .spinetoolbox\local directory and version controlled projects
• Item properties docks documentation. Items like Tool and Data Store have a lot of functionality in their Properties docks.

[ptsavol]

I think the User Guide is pretty good now. There are only a couple of unticked boxes in this issue if we don't count the Db Editor section (which was postponed to 0.8 anyway). There are some inconsistencies in formatting and some headers are not capitalized but other than that it looks good to me. Any volunteers in proofreading the whole thing?

[soininen]

I'm doing some proofreading.

[soininen]

I also think the User guide is now good enough for 0.7.

[soininen]

I think we can close this as Done now since 0.7 is out there. There is, however, good points under Other Things that need to be added which may later deserve their own issue(s).