From 23e46713b7bb0705be69065b65f387210d4a1939 Mon Sep 17 00:00:00 2001 From: Enquier Date: Tue, 2 May 2023 11:05:03 -0600 Subject: [PATCH] updating documentation --- docs/about.rst | 5 +- docs/conf.py | 4 +- docs/groups-docs-views.rst | 67 +++++++++++----------- docs/index.rst | 7 ++- docs/panes.rst | 110 +++++++++++-------------------------- docs/version-control.rst | 2 +- 6 files changed, 75 insertions(+), 120 deletions(-) diff --git a/docs/about.rst b/docs/about.rst index d5d0fce51..9e8bd9db8 100644 --- a/docs/about.rst +++ b/docs/about.rst @@ -3,7 +3,7 @@ About *************** -View Editor is a web-based environment designed to interact with a +View Editor (VE) is a web-based environment designed to interact with a systems model. VE is a document oriented view of the model elements, which are stored in OpenMBEE's Model Management Server (MMS). Its purpose is to provide real and true data through the web so that users may interact with actual model @@ -25,6 +25,3 @@ Authors can use model data, and share content across View Editor, in documents by **cross referencing** (see `Use Cross References <#use-cross-references>`__ ) -.. image:: media/image1.png - :width: 5.90069in - :height: 3.6519in \ No newline at end of file diff --git a/docs/conf.py b/docs/conf.py index 2fc43f5b0..c0c2fb881 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -6,8 +6,8 @@ copyright = '2013-2023, OpenMBEE Open Source Community' author = 'OpenMBEE Open Source Community' -release = '0.1' -version = '5.0.0' +release = '5.0.0-alpha' +version = 'v5' # -- General configuration diff --git a/docs/groups-docs-views.rst b/docs/groups-docs-views.rst index 6b17df0da..9228cf5f9 100644 --- a/docs/groups-docs-views.rst +++ b/docs/groups-docs-views.rst @@ -1,13 +1,14 @@ .. include:: images.rst +############################ Groups, Documents and Views -===================================================== +############################ The following documentations provide instructions on what View Editor "Group", "Document" and "Views" are and how to use them. Groups --------------------------------- +================================ .. |groups| image:: media/image62.png :width: 0.27779in @@ -16,7 +17,7 @@ Groups |groups| **Groups** organize documents and other groups within a project Create Group -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------- Since "Group" can only be used to organize documents/groups, it can only be created under the project level. @@ -43,7 +44,7 @@ be created under the project level. :height: 1.48619in Delete Group -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +-------------------------------------- Only an empty "Group" can be deleted. To delete "Super Classified Group" Group in the picture above,  @@ -69,7 +70,7 @@ Group in the picture above,  Follow the same steps to delete "Super Classified Group". Organize Groups/Documents -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------------------------- "Groups" can be used to group together documents/groups. To move documents into a group: @@ -103,7 +104,7 @@ documents into a group: peer.** Documents ------------------------------------ +=================================== A **Document** is composed of Views (see `Add Views <#add-a-new-view>`__), presentation @@ -115,7 +116,7 @@ To see how a user can sync the new document to MMS, refer to Update from MMS. Create Document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------- #. In the upper right go to the project home  |image37| @@ -131,7 +132,7 @@ Create Document button. Delete Document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +---------------- #. Select the document you wish to delete in the tree @@ -141,7 +142,7 @@ Delete Document To delete a view permanently, delete it from the model **and** then commit that delete to MMS. Structure/Edit Document -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------ #. Build high level document structure by creating `Views <#views>`__ @@ -163,7 +164,7 @@ advantage of using image, table, and equations PEs is that they: - appear in the left document navigation tree Views -------------------------------- +====== | Views are sections of a document that can hold pictures, diagrams, or textual information to describe ideas and objects. @@ -178,7 +179,7 @@ Views can be added to a document in three different ways: 3. Adding an existing View Add a New View -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------- Select the document (the root on the left pane). Click on the Add button  : @@ -194,7 +195,7 @@ Type in a name, and click on the "CREATE" button. :height: 2.69831in Add a New View as a Subview -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +----------------------------- Select the view under which you want to nest the subview and follow the same steps above: @@ -204,7 +205,7 @@ same steps above: :height: 1.91677in Add an Existing View -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------- To add an existing view to another document, select a document or view to which you want to nest the existing view under, and click on the Add @@ -241,7 +242,7 @@ Note: The original view will NOT be deleted upon the deletion of this view. Delete View -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------- A user can delete any existing view by selecting the view on the left pane, and clicking on the Delete button   from a document. @@ -256,7 +257,7 @@ Upon deletion, the browser redirects the user to the top of the document. Edit Views -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +------------------------------------ This section focuses on the **editing aspects** that View Editor offers including the following capabilities: @@ -291,7 +292,7 @@ detail. presentation elements to edit View content. Adding Text -''''''''''' +"""""""""""     The default PE for new Documents/Views is the text box. This will add a paragraph PE. @@ -305,7 +306,7 @@ add a paragraph PE. 4. Click on\ |image42|  to add content Adding Section -'''''''''''''' +"""""""""""""" Sections are used for adding concrete organization to views. They are similar to views in the sense that they provide a specific amount of @@ -323,7 +324,7 @@ be cross referenced. 5. You can nest other PEs to the section PE. Adding  Comment -''''''''''''''' +""""""""""""""" You can insert comments to all documents and views. Comments are saved in the model and are by default hidden from the view. See `Show @@ -331,7 +332,7 @@ Comments/Elements <#show-commentselements>`__ for more information. Adding Table -'''''''''''' +"""""""""""" You can add a table PE. Adding a separate table PE adds an element of organization (my naming and separating it from text) to the content. It @@ -346,7 +347,7 @@ also lets you cross reference the content directly. 4. Click on  |image46| to add content Adding Figure and Videos -'''''''''''''''''''''''' +"""""""""""""""""""""""" A user can add figures, such as images or videos, in an image PE. @@ -361,7 +362,7 @@ A user can add figures, such as images or videos, in an image PE.   Adding Equation -''''''''''''''' +""""""""""""""" A user can add an equation PE. @@ -374,7 +375,7 @@ A user can add an equation PE. 4. Click on |image50| to add content  Cross Reference as Link -''''''''''''''''''''''''''''''''''''''''''''''''' +""""""""""""""""""""""""""""""""""""""""""""""""" A Cross Reference as Link can be inserted to your view to reference an existing view or presentation element. @@ -467,7 +468,7 @@ for cross referencing in View Editor.   Create a Cross Reference - name, documentation, and value -''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +""""""""""""""""""""""""""""""""""""""""""""""""""""""""" - From 2.4.0 on, there is a checkbox in the cross reference popup that allows you to restrict the **editability** of the cross referenced @@ -475,7 +476,7 @@ Create a Cross Reference - name, documentation, and value center pane and not in the element specification on the right pane. Search and add Cross Reference through interface -'''''''''''''''''''''''''''''''''''''''''''''''' +"""""""""""""""""""""""""""""""""""""""""""""""" 1. Enable Edits |image54| @@ -507,7 +508,7 @@ Search and add Cross Reference through interface   Find Cross Reference inline  -'''''''''''''''''''''''''''' +"""""""""""""""""""""""""""" 1. Enable Edits |image56| @@ -544,7 +545,7 @@ You can reorder Views and Presentation Elements (PEs) to change the hierarchy of the elements. Reorder Views (Enhanced) -'''''''''''''''''''''''' +"""""""""""""""""""""""" 1. Click on the **"Reorder Views" button** on the **left pane**. @@ -593,7 +594,7 @@ view reordering page still showing numbers as if sections aren't numbered. We are working on a more robust reordering option. Reorder Presentation Elements (PEs) -''''''''''''''''''''''''''''''''''' +""""""""""""""""""""""""""""""""""" **1. Click on the "Reorder Content" button on the right pane.** @@ -615,7 +616,7 @@ For more information of other tools in the Right Pane, refer to `Right Pane Capabilities <#right-pane-capabilities>`__ Save As -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +--------------------------------- You can save Documents and Views locally. The following guides demonstrate the options for saving Views and Documents. @@ -671,7 +672,7 @@ See these subsections for more information about specific generations: 3. `PDF Customization <#pdf-customization>`__ Generate PDF of View/Document -''''''''''''''''''''''''''''''''''''''''''''''''''''''' +""""""""""""""""""""""""""""""""""""""""""""""""""""""" **Save View as PDF **\ |image60| @@ -742,7 +743,7 @@ the associated presentation elements Generate PDF with Model Based Cover Page -'''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''' +"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" In certain circumstances, you may want to create a custom cover page for a chosen document. The cover page is identified as the first View and @@ -783,7 +784,7 @@ Save to Word Document .. _step-by-step-instructions-1: Step-by-step instructions:  -''''''''''''''''''''''''''' +""""""""""""""""""""""""""" 1. Click on " *Export* " button, and select "*Export to Word*" (See below) @@ -802,7 +803,7 @@ Export Tables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Tables to CSV -''''''''''''' +""""""""""""'             |image64| @@ -820,7 +821,7 @@ Tables to CSV as a CSV file. Save all tables from document to CSV -'''''''''''''''''''''''''''''''''''' +"""""""""""""""""""""""""""""""""""" - Go to the full document by clicking on |image67|\ button. diff --git a/docs/index.rst b/docs/index.rst index 88b621f32..25fdd228e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -8,12 +8,15 @@ OpenMBEE View Editor Users Guide web. It implements the MMS REST API to provide a web environment to create, read, and update model elements, including Documents and Views. +Contents +-------- + .. toctree:: - :maxdepth: 3 + :maxdepth: 1 about panes - groups-documents-and-views + groups-docs-views search version-control advanced diff --git a/docs/panes.rst b/docs/panes.rst index b77effc57..3fce7a459 100644 --- a/docs/panes.rst +++ b/docs/panes.rst @@ -1,40 +1,41 @@ .. include:: images.rst -####################### -Panes -####################### +############ +Navigation +############ +View Editor is divided into a `navigation bar <#navigation-bar>`__ (red) and a content display area. The content area is divded into three +sections, the `left pane <#left-pane-capabilities>`__ or "tree-view" which displays the tree of the current context. The `center pane <#center-pane-capabilities>`__ shows the current +content and the `right pane <#right-pane-capabilities>`__ hosts a set of tools to further inspect and dive into the model content. + +.. image:: media/image1.png + :width: 5.90069in + :height: 3.6519in -******************** -Document View Panes -******************** -- `Navigation Bar - Capabilities <#navigation-bar>`__  - Shows + +- `Navigation Bar <#navigation-bar>`__  - Shows context of center pane (current project, branch, etc), allows management of branches and tags and provides global search and helpful links -- `Left Pane - Capabilities <#left-pane-capabilities>`__ - +- `Left Pane <#left-pane-capabilities>`__ - Shows the project/document hierarchies -- `Center Pane - Capabilities <#center-pane-capabilities>`__ +- `Center Pane <#center-pane-capabilities>`__ - Shows Document/View content, provides editing capabilities and export options -- `Right Pane - Capabilities <#right-pane-capabilities>`__ - +- `Right Pane <#right-pane-capabilities>`__ - Shows detailed information of the selected element, element history and more advanced features of View Editor - +=============== Navigation Bar =============== Top bar -------- +======= - Current **org** and option to switch @@ -46,7 +47,7 @@ Top bar Editor resources Second bar - current context ----------------------------- +============================ - First option on the left displays the **current project** and provides quick access to switch between other projects within @@ -60,8 +61,9 @@ Second bar - current context Tags <#version-control-branches-and-tags>`__ |  |image10| -Left Pane Capabilities -======================= +=============== +Left Pane +=============== The **Left Pane** has the following two display modes: @@ -79,7 +81,7 @@ Below are instructions showing how to use the Left Pane's tools, specifically while in a document The instruction includes: -------------------------- +========================= - Show/Hide Left Pane @@ -174,8 +176,9 @@ and out the pane. To delete a view from an existing document, refer to `Delete Views <#delete-view>`__. -Right Pane Capabilities -================================================= +=========== +Right Pane +=========== **The Right Pane** lets you inspect the element that is currently selected. @@ -217,7 +220,7 @@ with links to more information. Preview Element -------------------- +================ "Preview Element" tab displays the following information of the selected element: @@ -250,7 +253,7 @@ properties), depending on the type of element. :height: 6.54316in Edit and Save Elements ------------------------ +======================= Users can edit elements (refer to `Add Presentation Elements <#add-presentation-elements>`__) @@ -285,58 +288,8 @@ Note: There is an Auto Save plugin that tracks and stores changes in the browser's local storage  ( See `Autosave to the browser's localStorage <#autosave-to-the-browsers-localstorage>`__ ) -Autosave to the browser's localStorage -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -This feature automatically stores unsaved contents from any of the -CKEditors to the browser’s localStorage except for the editor on the -Comment's Modal, Proposal's Modal, Cross Reference Modal and Workspace's -description. The contents will be auto saved at a configurable interval -of 5 seconds and with the users’ consent reloaded automatically to the -editors which they belong. - -These auto saved contents are automatically deleted when either one of -the following conditions is met: - -1. Users press on one of the following buttons on the editor itself: - - a. save - - b. save and continue - - c. cancel: when the dialog shows up and users confirm the - cancellation - - d. delete: when the dialog shows up and users confirm the deletion - -2. Users press on one of the following buttons on the toolbar located on - the right side of the app's layout - - a. save - - b. save and continue - - c. cancel: when the dialog shows up and users confirm the - cancellation - - d. saveAll: This button is a little bit special because it shows up - in two different situations. - - i. Shows up after users click on the "Edit Element" button on the - toolbar located on the right side of the app's layout. In this - case, it will delete all the new auto saved contents related - to the specific element the user is editing. - - ii. Shows up after a user modifies one or more elements on the - page. In this case, it will delete all the new auto saved - contents corresponding to all these elements. - -When saving to a full capacity browser’s localStorage, all expired auto -saved contents will be automatically deleted to make room for new -contents. - Element History ------------------------------------------ +========================================= The **Element History tab** has a dropdown with a list of element versions. Select a version to display its attributes (same as `Preview @@ -356,7 +309,7 @@ To visualize the difference between 2 versions, check "Compare Versions" :height: 4.25944in Branches/Tags ---------------------------------------- +======================================= **Branches/Tags** can be accessed from the right pane. See `Branches and Tags <#version-control-branches-and-tags>`__ @@ -366,8 +319,9 @@ for more information :width: 5.04281in :height: 4.82054in -Center Pane Capabilities -================================================== +============= +Center Pane +============= The Center Pane lets you edit the view contents. diff --git a/docs/version-control.rst b/docs/version-control.rst index 9c6bcd9e9..b3f45ba58 100644 --- a/docs/version-control.rst +++ b/docs/version-control.rst @@ -1,5 +1,5 @@ ################### -Version Control: +Version Control ###################