GNOME.org
 

[gnome-builder] doc: update exploraing and related docs

commit 7472a96be40c633659d45b591f54f3c44c4bde51
Author: Christian Hergert <chergert redhat com>
Date:   Tue Mar 12 12:30:24 2019 -0700

    doc: update exploraing and related docs
    
    This gets some screenshots and documentation updated to how
    things look for 3.32.

 doc/help/_static/theme_overrides.css      |  14 ++-
 doc/help/conf.py                          |   4 +-
 doc/help/exploring.rst                    | 155 ++++++++++++++++++------------
 doc/help/figures/autocompletion.png       | Bin 185671 -> 300516 bytes
 doc/help/figures/commandbar.png           | Bin 217854 -> 112248 bytes
 doc/help/figures/editor.png               | Bin 371788 -> 545342 bytes
 doc/help/figures/file-search.png          | Bin 78249 -> 109804 bytes
 doc/help/figures/headerbar.png            | Bin 0 -> 57602 bytes
 doc/help/figures/inline-documentation.png | Bin 213982 -> 155125 bytes
 doc/help/figures/omnibar.png              | Bin 115519 -> 173422 bytes
 doc/help/figures/open-in-new-frame-1.png  | Bin 73383 -> 126716 bytes
 doc/help/figures/open-in-new-frame-2.png  | Bin 223608 -> 471203 bytes
 doc/help/figures/panels.png               | Bin 1070 -> 7151 bytes
 doc/help/figures/perspectives.png         | Bin 30308 -> 0 bytes
 doc/help/figures/preferences.png          | Bin 190625 -> 551598 bytes
 doc/help/figures/running.png              | Bin 0 -> 924730 bytes
 doc/help/figures/start-new-project.png    | Bin 0 -> 309445 bytes
 doc/help/figures/surfaces.png             | Bin 0 -> 47333 bytes
 doc/help/figures/symbol-search.png        | Bin 125218 -> 187178 bytes
 doc/help/figures/transfers.png            | Bin 96343 -> 67144 bytes
 doc/help/figures/workbench.png            | Bin 18407 -> 0 bytes
 doc/help/figures/workspace_menu.png       | Bin 0 -> 124384 bytes
 doc/help/installation.rst                 |   2 -
 doc/help/plugins/enabling.rst             |   6 +-
 24 files changed, 109 insertions(+), 72 deletions(-)
---
diff --git a/doc/help/_static/theme_overrides.css b/doc/help/_static/theme_overrides.css
index 7b5d7fcf4..f41e5e60f 100644
--- a/doc/help/_static/theme_overrides.css
+++ b/doc/help/_static/theme_overrides.css
@@ -25,7 +25,7 @@ h2 {
   font-family: "Source Sans Pro", sans-serif;
   font-size: 24pt;
   font-weight: 400;
-  color: #4a86cf;
+  color: #3584e4;
 }
 
 h3 {
@@ -79,9 +79,9 @@ span.std.std-ref {
 }
 
 div.admonition.note {
-  background-color: #4a86cf33; }
+  background-color: #3584e433; }
 div.admonition.note .first {
-  background-color: #4a86cf; }
+  background-color: #3584e4; }
 
 div.admonition.tip {
   background-color: #01808e33; }
@@ -102,10 +102,14 @@ a.icon-home, a.icon-home:hover {
   content: "";
 }
 
+.wy-body-for-nav {
+  background-color: #f6f5f4;
+}
+
 .wy-side-nav-search {
-  background-color: #4a86cf;
+  background-color: #3584e4;
 }
 
-a, a:visited { color: #4a86cf; }
+a, a:visited { color: #3584e4; }
   .wy-menu a { color: #808080; }
   .wy-side-nav-search a { color: #fff; }
diff --git a/doc/help/conf.py b/doc/help/conf.py
index 49a9dd640..3cfde99d4 100644
--- a/doc/help/conf.py
+++ b/doc/help/conf.py
@@ -58,9 +58,9 @@ author = 'Christian Hergert, et al.'
 # built documents.
 #
 # The short X.Y version.
-version = '3.31'
+version = '3.32'
 # The full version, including alpha/beta/rc tags.
-release = '3.31.1'
+release = '3.32.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.
diff --git a/doc/help/exploring.rst b/doc/help/exploring.rst
index c710cf2a3..3edf1c523 100644
--- a/doc/help/exploring.rst
+++ b/doc/help/exploring.rst
@@ -4,83 +4,112 @@ Exploring the Interface
 
 The following sections will help you get to know Builder.
 
- * `Project Greeter`_
- * `Workbench Window`_
+ * `Greeter`_
+ * `Starting a New Project`_
+ * `Workbench`_
+ * `Workspace`_
  * `Header Bar`_
- * `Switching Perspectives`_
+ * `Switching Surfaces`_
  * `Showing and Hiding Panels`_
  * `Build your Project`_
+ * `Running`_
  * `Editor`_
  * `Autocompletion`_
  * `Documentation`_
- * `Splitting Windows`_
+ * `Splitting Pages`_
  * `Searching`_
  * `Preferences`_
  * `Command Bar`_
- * `Transfers`_
+ * `Ongoing Tasks`_
 
-Project Greeter
----------------
+Greeter
+-------
 
 When you start Builder, you will be asked to select a project to be opened:
 
 .. image:: figures/greeter.png
-   :width: 555 px
+   :width: 500 px
    :align: center
 
-The window displays projects that were discovered on your system.
-By default, the ``~/Projects`` directory will be scanned for projects when Builder starts.
-Projects you have previously opened will be shown at the top.
+The greeter window will display projects that you have previously opened.
+Additionally, it contains projects that you might be interested in contributing to.
+
+Using the buttons at the bottom of the window, you man create a new project, select an existing project on 
disk, or clone a source code repository.
 
-Selecting a project row opens the project or pressing "Enter" will open the last project that was open.
-You can also start typing to search the projects followed by "Enter" to open.
+Selecting a project row opens the project.
+Pressing "Enter" from the search box will open the first project matching the requested search text.
 
 If you'd like to remove a previously opened project from the list, activate *Selection mode*.  
-Press the "Select" button in the top right corner to the left of the close application button and
-then select the row you would like to remove. 
-Select the row(s) you'd like to remove and then click "Remove" in the lower left corner of the window.
+Press the "checkmark" button in the top right corner and then select the rows you would like to remove. 
+Then click "Remove Projects" at the bottom of the window.
+
+Starting a New Project
+----------------------
+
+Builder provides templates for a few kinds of projects.
+From the `Greeter`_, select "Start New Project" and fill out the requested information.
+
+.. image:: figures/start-new-project.png
+   :width: 512 px
+   :align: center
+
+Click "Create Project" to get started.
+
+Workbench
+---------
+
+A project "workbench" is a collection of windows used for your project.
+For users with a single monitor, this is generally a single window.
+But for multi-monitor users, multiple `Workspace`_ windows may be part of the same workbench.
+
+Workspace
+---------
 
-Workbench Window
-----------------
+The window containing your project is called a "**Workspace**".
+A workspace contains the `Header Bar`_ and a number of **Surfaces**.
 
-The application window containing your project is called the "**Workbench Window**".
-The Workbench is split up into two main areas.
-At the top is the `Header Bar`_ and below is the current "**Perspective**".
+Builder has many surfaces, including the Editor, Build Preferences, and the Profiler.
+Plugins may provide additional surfaces.
 
-Builder has many perspectives, including the Editor, Build Preferences, Application Preferences, and the 
Profiler.
+You can switch surfaces using the surface selector in the top-left of the `Header Bar`_.
 
 Header Bar
 ----------
 
-The header bar is shown below.
-This contains a button in the top left for `Switching Perspectives`_.
-In the center is the "OmniBar" which can be used to `Build your Project`_.
+The header bar is at the top of the `Workspace`_.
+This contains a button in the top-left for `Switching Surfaces`_.
+In the center is the "Omni Bar" which can be used to `Build your Project`_.
 
-.. image:: figures/workbench.png
+.. image:: figures/headerbar.png
    :align: center
 
-To the right of the OmniBar is the *Run* button.
+To the right of the Omni Bar is the *Run* button.
 Clicking the arrow next to *Run* allows you to change how Builder will run your application.
 You can run normally, with a debugger, profiler, or even with Valgrind.
 
-On the right is the search box.
+On the right is the search box which you can focus with ``Control+.``.
 Type a few characters from the file you would like to open and it will fuzzy search your project tree.
-Use "Enter" to complete the request and open the file.
+Use "Enter" to open the file.
 
-To the right of the search box is the workbench menu.
-You can find less-used features here.
+To the right of the search box is the workspace menu.
+You can find less-used items here.
+If you are having an issue with Builder, you can use the "Generate Support Log" item to create a file which 
helps us troubleshoot your issue.
 
-Switching Perspectives
-----------------------
+.. image:: figures/workspace_menu.png
+   :width: 225 px
+   :align: center
+
+Switching Surfaces
+------------------
 
-To switch perspectives, click the perspective selector button in the top left of the workbench window.
-Perspectives that support a keyboard accelerator will display the appropriate accelerator next to name of 
the perspective.
+To switch surfaces, click the perspective selector button in the top left of the workbench window.
+Surfaces that support a keyboard accelerator will display the appropriate accelerator next to name of the 
perspective.
 
-.. image:: figures/perspectives.png
-   :width: 295 px
+.. image:: figures/surfaces.png
+   :width: 271 px
    :align: center
 
-Select the row to change perspectives.
+Select the row to change the surface.
 
 Showing and Hiding Panels
 -------------------------
@@ -89,13 +118,14 @@ Sometimes panels get in the way of focusing on code.
 You can move them out of the way using the buttons in the top left of the workbench window.
 
 .. image:: figures/panels.png
-   :width: 133 px
+   :width: 145 px
    :align: center
 
 When entering Fullscreen mode, Builder will automatically dismiss the panels for your convenience.
 
 Additionally, you can use the "left-visible" or "bottom-visible" commands from the `Command Bar`_ to toggle 
their visibility.
 
+
 Build your Project
 ------------------
 
@@ -103,7 +133,7 @@ To build your project, use the OmniBar in the center of the header bar.
 To the right of the OmniBar is a button for starting a build as shown in the image below.
 
 .. image:: figures/omnibar.png
-   :width: 708 px
+   :width: 641 px
    :align: center
 
 You can also use the "build", "rebuild", "install", or "clean" commands from the command bar.
@@ -111,8 +141,16 @@ You can also use the "build", "rebuild", "install", or "clean" commands from the
 While the project is building, the build button will change to a cancel button.
 Clicking the cancel button will abort the current build.
 
-.. image:: figures/building.png
-   :width: 623 px
+
+Running
+-------
+
+Clicking the "Run" button in the `Header Bar`_ will ensure your application is built and then execute it 
within the selected runtime environment.
+While the application is running, the "Run" button will change to a "Stop" button.
+Clicking the "Stop" button will force the application to exit (usually with a ``SIGTERM``).
+
+.. image:: figures/running.png
+   :width: 707 px
    :align: center
 
 
@@ -123,7 +161,7 @@ When Builder opens your project, it will place you in the editor perspective.
 This is where you develop your project.
 
 .. image:: figures/editor.png
-   :width: 1415 px
+   :width: 612 px
    :align: center
 
 Along the left is the project sidebar. It contains the project tree, list of
@@ -133,6 +171,7 @@ open documents, todo items, and build errors. Generally, it contains the
 Along the bottom is the utilities panel. Here you will find things like the
 debugger, terminal, build, and application console.
 
+
 Autocompletion
 --------------
 
@@ -140,7 +179,7 @@ Builder has built-in support for various autocompletion engines.
 Start typing to get word suggestions.
 
 .. image:: figures/autocompletion.png
-   :width: 960 px
+   :width: 1039 px
    :align: center
 
 Documentation
@@ -151,18 +190,18 @@ You can also use ``F2`` to bring up the documentation with your insertion cursor
 Use ``Shift+K`` if you're using Vim keybindings.
 
 .. image:: figures/inline-documentation.png
-   :width: 1024 px
+   :width: 469 px
    :align: center
 
 
-Splitting Windows
------------------
+Splitting Pages
+---------------
 
 Builder can show you multiple editors side-by-side.
 In the editor view use "Open in New Frame" to split a document into two views.
 
 .. image:: figures/open-in-new-frame-1.png
-   :width: 396 px
+   :width: 357 px
    :align: center
 
 Afterwards, you'll see the editors side-by-side like such:
@@ -183,7 +222,7 @@ To focus the search entry with the keyboard use ``Control+.``.
 You can fuzzy search for files by typing a few characters from the file name.
 
 .. image:: figures/file-search.png
-   :width: 629 px
+   :width: 535 px
    :align: center
 
 
@@ -191,7 +230,7 @@ Builder will automatically index your project into a database if it uses a suppo
 You can search this database to jump to code such as functions or classes.
 
 .. image:: figures/symbol-search.png
-   :width: 605 px
+   :width: 531 px
    :align: center
 
 
@@ -214,22 +253,18 @@ You can type various actions to activate them.
 To display the command bar, use the ``Control+Enter`` keyboard shortcut.
 You can release the command bar by pressing ``Escape`` and return to the editor.
 
-The command bar includes completion using ``Tab``, similar to the terminal.
-Use this to explore the availble commands.
-
 .. image:: figures/commandbar.png
-   :width: 1113 px
+   :width: 640 px
    :align: center
 
 
-Transfers
----------
+Ongoing Tasks
+-------------
 
-Sometimes it might be necessary for Builder to download content from the
-internet to build your project. When this happens, you'll see a transfers
-button displaying the progress in the top right.
+Sometimes it might be necessary for Builder to download content from the internet to build your project or 
perform other long-running tasks.
+When this happens, a button is displayed with information about those operations.
 
 .. image:: figures/transfers.png
-   :width: 527 px
+   :width: 438 px
    :align: center
 
diff --git a/doc/help/figures/autocompletion.png b/doc/help/figures/autocompletion.png
index bfeb06d29..8c06152ac 100644
Binary files a/doc/help/figures/autocompletion.png and b/doc/help/figures/autocompletion.png differ
diff --git a/doc/help/figures/commandbar.png b/doc/help/figures/commandbar.png
index 17d366148..ba701030d 100644
Binary files a/doc/help/figures/commandbar.png and b/doc/help/figures/commandbar.png differ
diff --git a/doc/help/figures/editor.png b/doc/help/figures/editor.png
index 9a30711aa..75288e4e7 100644
Binary files a/doc/help/figures/editor.png and b/doc/help/figures/editor.png differ
diff --git a/doc/help/figures/file-search.png b/doc/help/figures/file-search.png
index 811249e9d..9bb63688e 100644
Binary files a/doc/help/figures/file-search.png and b/doc/help/figures/file-search.png differ
diff --git a/doc/help/figures/headerbar.png b/doc/help/figures/headerbar.png
new file mode 100644
index 000000000..9b24f65a5
Binary files /dev/null and b/doc/help/figures/headerbar.png differ
diff --git a/doc/help/figures/inline-documentation.png b/doc/help/figures/inline-documentation.png
index 0dd3204e7..aa647b4d4 100644
Binary files a/doc/help/figures/inline-documentation.png and b/doc/help/figures/inline-documentation.png 
differ
diff --git a/doc/help/figures/omnibar.png b/doc/help/figures/omnibar.png
index e08e57939..5728b5e7c 100644
Binary files a/doc/help/figures/omnibar.png and b/doc/help/figures/omnibar.png differ
diff --git a/doc/help/figures/open-in-new-frame-1.png b/doc/help/figures/open-in-new-frame-1.png
index 905475a7e..1e95fdfdb 100644
Binary files a/doc/help/figures/open-in-new-frame-1.png and b/doc/help/figures/open-in-new-frame-1.png differ
diff --git a/doc/help/figures/open-in-new-frame-2.png b/doc/help/figures/open-in-new-frame-2.png
index 7176294a8..2692a5aaf 100644
Binary files a/doc/help/figures/open-in-new-frame-2.png and b/doc/help/figures/open-in-new-frame-2.png differ
diff --git a/doc/help/figures/panels.png b/doc/help/figures/panels.png
index 557ffa724..74729f6a2 100644
Binary files a/doc/help/figures/panels.png and b/doc/help/figures/panels.png differ
diff --git a/doc/help/figures/preferences.png b/doc/help/figures/preferences.png
index 227ae34f9..4f761a3a6 100644
Binary files a/doc/help/figures/preferences.png and b/doc/help/figures/preferences.png differ
diff --git a/doc/help/figures/running.png b/doc/help/figures/running.png
new file mode 100644
index 000000000..d48120ee3
Binary files /dev/null and b/doc/help/figures/running.png differ
diff --git a/doc/help/figures/start-new-project.png b/doc/help/figures/start-new-project.png
new file mode 100644
index 000000000..f25f4b77a
Binary files /dev/null and b/doc/help/figures/start-new-project.png differ
diff --git a/doc/help/figures/surfaces.png b/doc/help/figures/surfaces.png
new file mode 100644
index 000000000..2bafddd27
Binary files /dev/null and b/doc/help/figures/surfaces.png differ
diff --git a/doc/help/figures/symbol-search.png b/doc/help/figures/symbol-search.png
index 8dabca65f..1e4af02cf 100644
Binary files a/doc/help/figures/symbol-search.png and b/doc/help/figures/symbol-search.png differ
diff --git a/doc/help/figures/transfers.png b/doc/help/figures/transfers.png
index 61e13a38e..0c6716459 100644
Binary files a/doc/help/figures/transfers.png and b/doc/help/figures/transfers.png differ
diff --git a/doc/help/figures/workspace_menu.png b/doc/help/figures/workspace_menu.png
new file mode 100644
index 000000000..dabaa3fbd
Binary files /dev/null and b/doc/help/figures/workspace_menu.png differ
diff --git a/doc/help/installation.rst b/doc/help/installation.rst
index 4dad298f0..02deac925 100644
--- a/doc/help/installation.rst
+++ b/doc/help/installation.rst
@@ -28,8 +28,6 @@ If Software_ does not automatically open, try opening the Stable_ flatpakref by
 
 If you want to track Builder development, you might want the Nightly_ channel instead of Stable_.
 
-.. note:: To build flatpak-based applications, ensure that the ``flatpak-builder`` program is installed. On 
Fedora, this is the ``flatpak-builder`` package.
-
 Command Line
 ^^^^^^^^^^^^
 
diff --git a/doc/help/plugins/enabling.rst b/doc/help/plugins/enabling.rst
index dc2e37d21..11b67183e 100644
--- a/doc/help/plugins/enabling.rst
+++ b/doc/help/plugins/enabling.rst
@@ -6,11 +6,11 @@ Builder is built to be extensible from the ground up.
 In fact, many features of Builder are created as extensions.
 To customize Builder for your workflow you may want to enable or disable some extensions.
 
-To enable or disable an extension, use the perspective selector and navigate to "Preferences".
+To enable or disable an extension, open the application "Preferences" from the workspace menu.
 You can also use the keyboard shortcut ``Control+,``.
 
-.. image:: ../figures/perspectives.png
-   :width: 295 px
+.. image:: ../figures/workspace_menu.png
+   :width: 300 px
    :align: center
 
 You'll be presented with the preferences perspective which looks like:
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]