Documentation of ERD Diagram support. Fixes #6152

docs/en_US/developer_tools.rst

@@ -15,3 +15,4 @@ PL/SQL code.
    query_tool
    editgrid
    schema_diff
+   erd_tool

docs/en_US/erd_tool.rst

@@ -0,0 +1,232 @@
+.. _erd_tool:
+
+*****************
+`ERD Tool`:index:
+*****************
+
+The Entity-Relationship Diagram (ERD) tool is a database design tool that provides a graphical representation of database tables, columns, and inter-relationships. ERD can give sufficient information for the database administrator to follow when developing and maintaining the database. The ERD Tool allows you to:
+
+* Design and visualize the database tables and their relationships.
+* Add notes to the diagram.
+* Auto-align the tables and links for cleaner visualization.
+* Save the diagram and open it later to continue working on it.
+* Generate ready to run SQL from the database design.
+* Generate the database diagram for an existing database.
+
+.. image:: images/erd_tool.png
+    :alt: ERD tool window
+    :align: center
+
+You can open multiple copies of the ERD tool in individual tabs simultaneously. To close a copy of the ERD tool, click the *X* in the upper-right hand corner of the tab bar.
+
+Toolbar
+*******
+
+The *ERD Tool* toolbar uses context-sensitive icons that provide shortcuts to frequently performed tasks. The option is enabled for the highlighted icon and is disabled for the grayed-out icon.
+
+.. image:: images/erd_tool_toolbar.png
+    :alt: ERD tool toolbar
+    :align: center
+
+Hover over an icon on Toolbar to display a tooltip that describes the icon's functionality.
+
+File Options
+************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *Open File*          | Click the *Open File* icon to load a previously saved diagram.                                    | Ctrl + O       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Save*               | Click the *Save* icon to perform a quick-save of a previously saved diagram, or to save the       | Ctrl + S       |
+   |                      | diagram to a file.                                                                                |                |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Save as*            | Click the *Save As* to open a new browser dialog and specify a new location to save the diagram.  | Ctrl + Shift + |
+   |                      |                                                                                                   | S              |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Export Options
+**************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *Generate SQL*       | Click the *Generate SQL* icon to generate the DDL SQL for the diagram and open a query tool       | Option + Ctrl +|
+   |                      | with the generated SQL ready for execution.                                                       | S              |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Editing Options
+***************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *Add table*          | Click this button to add a new table to the diagram. On clicking, this will open a table dialog   | Option/Alt +   |
+   |                      | where you can put the table details.                                                              | Ctrl + A       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Edit table*         | Click this button to edit a table on the diagram. On clicking, this will open a table dialog      | Option/Alt +   |
+   |                      | where you can change table details. This will enable when a table is selected.                    | Ctrl + E       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Clone table*        | Click this button to clone the complete table structure, name it with a auto generated name and   | Option/Alt +   |
+   |                      | put it in the diagram.                                                                            | Ctrl + C       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Drop table/link*    | You can drop a table or link using this button. You need to select a table or link and click on   | Option/Alt +   |
+   |                      | this button to drop it.                                                                           | Ctrl + D       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Table Relationship Options
+**************************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *1M*                 | Click this button to open a one-to-many relationship dialog to add a relationship between the     | Option/Alt +   |
+   |                      | two tables. The selected table becomes the referencing table and will have the *many* endpoint of | Ctrl + O       |
+   |                      | the link.                                                                                         |                |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *MM*                 | Click this button to open a many-to-many relationship dialog to add a relationship between the    | Option/Alt +   |
+   |                      | two tables. This option will create a new table based on the selected columns for the two relating| Ctrl + M       |
+   |                      | tables and link them.                                                                             |                |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Utility Options
+***************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *Add/Edit note*      | Click this button to make notes on tables nodes while designing the database.                     | Option/Alt +   |
+   |                      |                                                                                                   | Ctrl + N       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Auto align*         | Click this button to auto align all tables and links to make it look more cleaner.                | Option/Alt +   |
+   |                      |                                                                                                   | Ctrl + L       |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Show details*       | Click this button to toggle the column details visibility. It allows you to show few or more      | Option/Alt +   |
+   |                      | column details.                                                                                   | Shift + D      |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Zoom Options
+************
+
+.. table::
+   :class: longtable
+   :widths: 1 4 1
+
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | Icon                 | Behavior                                                                                          | Shortcut       |
+   +======================+===================================================================================================+================+
+   | *Zoom to fit*        | Click this button to zoom in/out automatically and fit all the tables to the view.                | Option/Alt +   |
+   |                      |                                                                                                   | Shift + F      |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Zoom in*            | Click this button to zoom in the diagram.                                                         | Option/Alt +   |
+   |                      |                                                                                                   | Shift + "+"    |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+   | *Zoom out*           | Click this button to zoom out the diagram.                                                        | Option/Alt +   |
+   |                      |                                                                                                   | Shift + "-"    |
+   +----------------------+---------------------------------------------------------------------------------------------------+----------------+
+
+Table Dialog
+************
+
+.. image:: images/erd_table_dialog.png
+    :alt: ERD tool table dialog
+    :align: center
+
+The table dialog allows you to:
+
+* Change the table structure details.
+* It can be used edit an existing table or add a new one.
+* Refer :ref:`table dialog <table_dialog>` for information on different fields.
+
+Table Node
+**********
+
+.. image:: images/erd_table_node.png
+    :alt: ERD tool table node
+    :align: center
+
+The table node shows table details in a graphical representation:
+
+* The top bar has a *details toggle button* that is used to toggle column details visibility. There is also a *note button* that is visible only if there is some note added. you can click on this button to quickly change the note.
+* The first row shows the schema name of the table. Eg. *public* in above image.
+* The second row shows the table name. Eg. *users* in above image.
+* All other rows below the table name are the columns of the table along with data type. If the column is a primary key then it will have lock key icon eg. id is the primary key in above image. Otherwise, it will have column icon.
+* you can click on the node and drag to move on the canvas.
+* Upon double click on the table node or by clicking the edit button from the toolbar, the table dialog opens where you can change the table details. Refer :ref:`table dialog <table_dialog>` for information on different fields.
+
+The One to Many Link Dialog
+***************************
+
+.. image:: images/erd_1m_dialog.png
+    :alt: ERD tool 1M dialog
+    :align: center
+
+The one to many link dialog allows you to:
+
+* Add a foregin key relationship between two tables.
+* *Local Table* is the table that references a table and has the *many* end point.
+* *Local Column* the column that references.
+* *Referenced Table* is the table that is being referred and has the *one* end point.
+* *Referenced Column* the column that is being referred.
+
+The Many to Many Link Dialog
+****************************
+
+.. image:: images/erd_mm_dialog.png
+    :alt: ERD tool MM dialog
+    :align: center
+
+The many to many link dialog allows you to:
+
+* Add a many to many relationship between two tables.
+* It creates a relationship tables having columns derived from the two tables and link them to the tables.
+* *Left Table* is the first table that is to be linked. It will receive the *one* endpoint of the link with the new relation table.
+* *Left Column* the column of the first table, that will always be a primary key.
+* *Right Table* is the second table that is to be linked. It will receive the *one* endpoint of the link with the new relation table.
+* *Right Column* the column of the second table, that will always be a primary key.
+
+The Table Link
+**************
+
+.. image:: images/erd_table_link.png
+    :alt: ERD tool table link
+    :align: center
+
+The table link shows relationship between tables:
+
+* The single line endpoint of the link shows the column that is being referred.
+* The three line endpoint of the link shows the column that refers.
+* If one of the columns that is being referred or that refers is removed from the table then the link will get dropped.
+* you can click on the link and drag to move on the canvas.
+
+
+The Table Notes
+***************
+
+.. image:: images/erd_table_note.png
+    :alt: ERD tool table note
+    :align: center
+
+* You can use the notes popup to mark some notes while designing the database.
+* You open the pop-up using the toolbar note button.
+* If some note is added to a table then it will have notes button on the table node. You can click on the button to check/update notes.

docs/en_US/menu_bar.rst

@@ -76,6 +76,9 @@ following options (in alphabetical order):
 +-----------------------------+--------------------------------------------------------------------------------------------------------------------------+
 | *View Data*                 | Click to access a context menu that provides several options for viewing data (see below).                               |
 +-----------------------------+--------------------------------------------------------------------------------------------------------------------------+
+| *Generate ERD*              | Click to open the ERD tool with automatically generated diagram for the database selected.                               |
+|                             | This option is available only when a database is selected. Options are displayed on the flyout menu.                     |
++-----------------------------+--------------------------------------------------------------------------------------------------------------------------+
 
 The Tools Menu
 **************
@@ -116,6 +119,8 @@ Use the *Tools* menu to access the following options (in alphabetical order):
 +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
 | *Storage Manager*         | Click to open the :ref:`Storage Manager <storage_manager>` to upload, delete, or download the backup files.                               |
 +---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
+| *New ERD Project*         | Click to open the :ref:`ERD Tool <erd_tool>` and start designing your database.                                                           |
++---------------------------+-------------------------------------------------------------------------------------------------------------------------------------------+
 
 The Help Menu
 *************

docs/en_US/release_notes_4_30.rst

@@ -12,6 +12,7 @@ New features
 | `Issue #1802 <https://redmine.postgresql.org/issues/1802>`_ -  Added ERD Diagram support with basic table fields, primary key, foreign key, and DDL SQL generation.
 | `Issue #5457 <https://redmine.postgresql.org/issues/5457>`_ -  Added support for Kerberos authentication, using SPNEGO to forward the Kerberos tickets through a browser.
 | `Issue #6147 <https://redmine.postgresql.org/issues/6147>`_ -  Documentation of Kerberos support.
+| `Issue #6152 <https://redmine.postgresql.org/issues/6152>`_ -  Documentation of ERD Diagram support.
 | `Issue #6160 <https://redmine.postgresql.org/issues/6160>`_ -  Add a container option (PGADMIN_DISABLE_POSTFIX) to disable the Postfix server.
 
 Housekeeping

web/pgadmin/tools/erd/static/js/erd_tool/ui_components/BodyWidget.jsx

@@ -321,7 +321,7 @@ export default class BodyWidget extends React.Component {
   }
 
   onHelpClick() {
-    let url = url_for('help.static', {'filename': 'erd.html'});
+    let url = url_for('help.static', {'filename': 'erd_tool.html'});
     window.open(url, 'pgadmin_help');
   }
 
@@ -624,14 +624,14 @@ export default class BodyWidget extends React.Component {
             shortcut={this.state.preferences.drop_table} disabled={!this.state.any_item_selected}/>
         </ButtonGroup>
         <ButtonGroup>
-          <IconButton id="add-note" icon="fa fa-sticky-note" onClick={this.onNoteClick} title={gettext('Add/Edit note')}
-            shortcut={this.state.preferences.add_edit_note} disabled={!this.state.single_node_selected || this.state.single_link_selected}/>
           <IconButton id="add-onetomany" text="1M" onClick={this.onOneToManyClick} title={gettext('One-to-Many link')}
             shortcut={this.state.preferences.one_to_many} disabled={!this.state.single_node_selected || this.state.single_link_selected}/>
           <IconButton id="add-manytomany" text="MM" onClick={this.onManyToManyClick} title={gettext('Many-to-Many link')}
             shortcut={this.state.preferences.many_to_many} disabled={!this.state.single_node_selected || this.state.single_link_selected}/>
         </ButtonGroup>
         <ButtonGroup>
+          <IconButton id="add-note" icon="fa fa-sticky-note" onClick={this.onNoteClick} title={gettext('Add/Edit note')}
+            shortcut={this.state.preferences.add_edit_note} disabled={!this.state.single_node_selected || this.state.single_link_selected}/>
           <IconButton id="auto-align" icon="fa fa-magic" onClick={this.onAutoDistribute} title={gettext('Auto align')}
             shortcut={this.state.preferences.auto_align} />
           <DetailsToggleButton id="more-details" onClick={this.onDetailsToggle} showDetails={this.state.show_details} />