Restructure documentation

Author: paceholder

LICENSE

@@ -0,0 +1,28 @@
+BSD-3-Clause license
+====================
+
+Copyright (c) 2017, Dmitry Pinaev
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+  * Redistributions of source code must retain the above copyright notice, this
+    list of conditions and the following disclaimer.
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+  * Neither the name of copyright holder, nor the names of its contributors may
+    be used to endorse or promote products derived from this software without
+    specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
+IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

LICENSE.rst

@@ -10,13 +10,13 @@ simple graph visualization and editing or extended further for using the
 `Dataflow paradigm <https://en.wikipedia.org/wiki/Dataflow_programming>`_ .
 
 The library is written using the Model-View approach. The whole graph structure
-is defined by the user-provided ``GraphModel`` class. It is possible to create or
-add Nodes and Connections. The underlying data structures could be of any
-arbitrary type or representation.
+is defined by the user-provided class deriving from ``AbstractGraphModel`` class.
+It is possible to create or add Nodes and Connections. The underlying data
+structures could be of any arbitrary type or representation.
 
-The ``GraphModel`` could or could not be attached to specialized
-``QGraphicsScene`` and ``QGraphicsView`` objects. I.e. the so-called "headless"
-`modus operandi` is possible.
+An instance of ``AbstractGraphModel`` could or could not be attached to
+specialized ``QGraphicsScene`` and ``QGraphicsView`` objects. I.e. the so-called
+"headless" `modus operandi` is possible.
 
 
 .. contents:: Navigation
@@ -36,8 +36,11 @@ fetches available data and propagates is further. Each change in the source node
 is immediately propagated through all the connections updating the whole graph.
 
 
-Supported Platforms
-===================
+Supported Environments
+======================
+
+Platforms
+---------
 
 * Linux (x64, gcc-7.0, clang-7) |ImageLink|_
 * OSX (Apple Clang - LLVM 3.6) |ImageLink|_
@@ -52,7 +55,7 @@ Supported Platforms
 .. _AppveyorImage: https://ci.appveyor.com/project/paceholder/nodeeditor/branch/master)
 
 Dependencies
-============
+------------
 
 * Qt >5.2
 * CMake 3.2
@@ -75,7 +78,7 @@ Building
 ========
 
 Linux
-^^^^^
+-----
 
 ::
 
@@ -88,7 +91,7 @@ Linux
 
 
 Qt Creator
-^^^^^^^^^^
+----------
 
 1. Open `CMakeLists.txt` as project.
 2. If you don't have the `Catch2` library installed, go to `Build Settings`, disable the checkbox `BUILD_TESTING`.
@@ -97,8 +100,8 @@ Qt Creator
 5. Click the button `Run`
 
 
->>> Version 3 Roadmap <<<
-=========================
+Version 3 Roadmap
+=================
 
 #. Headless mode. [done]
    You can create, populate, modify the derivative of AbstractGraphModel
@@ -124,12 +127,37 @@ Qt Creator
 Any suggestions are welcome!
 
 
+Contributing
+============
+
+#. Be polite, respectful and collaborative.
+#. For submitting a bug:
+
+    #. Describe your environment (Qt version, compiler, OS etc)
+    #. Describe steps to reproduce the issue
+
+#. For submitting a pull request:
+
+   #. Create a proposal task first. We can come up with a better design together.
+   #. Create a pull-request. If applicable create a simple example to your
+         iescribe your problem in details, provide use cases,
+
+#. For submitting a development request:
+
+   #. Describe your issue in details
+   #. Provide some use cases.
+
+#. I maintain this probject in my free time, when I am not busy with my work or
+   my family. **If I do not react or do not answer for too long, please ping
+   me**.
+
+
 Citing
 ======
 
 ::
 
-    Dmitry Pinaev et al, Qt5 Node Editor, (2017), GitHub repository, https://github.com/paceholder/nodeeditor
+    Dmitry Pinaev et al, Qt Node Editor, (2017), GitHub repository, https://github.com/paceholder/nodeeditor
 
 BibTeX::
 
@@ -160,7 +188,7 @@ Showcase
 ========
 
 Youtube videos
-^^^^^^^^^^^^^^
+--------------
 
 .. image:: https://img.youtube.com/vi/pxMXjSvlOFw/0.jpg
    :target: https://www.youtube.com/watch?v=pxMXjSvlOFw
@@ -171,7 +199,7 @@ Youtube videos
    :target: https://www.youtube.com/watch?v=i_pB-Y0hCYQ
 
 CANdevStudio
-^^^^^^^^^^^^
+------------
 
 `CANdevStudio <https://github.com/GENIVI/CANdevStudio>`_ is a cost-effective,
 cross-platform replacement for CAN simulation software. CANdevStudio enables to
@@ -180,26 +208,26 @@ every automotive developer. Thanks to modularity it is easy to implement new,
 custom features.
 
 
-.. image:: pictures/showcase_CANdevStudio.png
+.. image:: docs/_static/showcase_CANdevStudio.png
 
 
 Chigraph
-^^^^^^^^
+--------
 
 `Chigraph <https://github.com/chigraph/chigraph>`_ is a visual programming
 language for beginners that is unique in that it is an intuitive flow graph:
 
-.. image:: pictures/chigraph.png
+.. image:: docs/_static/chigraph.png
 
 
 It features easy bindings to C/C++, package management, and a cool interface.
 
 
 Spkgen particle editor
-^^^^^^^^^^^^^^^^^^^^^^
+----------------------
 
 `Spkgen <https://github.com/fredakilla/spkgen>`_ is an editor for the SPARK
 particles engine that uses a node-based interface to create particles effects for
 games
 
-.. image:: pictures/spkgen.png
+.. image:: docs/_static/spkgen.png

README.rst

@@ -11,7 +11,8 @@ if(DOXYGEN_FOUND)
   set(DOXYGEN_INDEX_FILE ${CMAKE_CURRENT_BINARY_DIR}/html/index.html)
 
   set(DOXYGEN_INPUT_DIR ${PROJECT_SOURCE_DIR}/src
-                        ${PROJECT_SOURCE_DIR}/include)
+                        ${PROJECT_SOURCE_DIR}/include
+                        ${PROJECT_SOURCE_DIR}/examples/calculator)
   # Making string joined with " "
   list(JOIN DOXYGEN_INPUT_DIR " " DOXYGEN_INPUT_DIR_JOINED)
 

docs/CMakeLists.txt

@@ -2,10 +2,12 @@ QtNodes Documentation
 =====================
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 3
 
     overview
+    todo
     classes
+    license_link
 
 Index
 ==================

docs/index.rst

@@ -0,0 +1 @@
+.. include:: ../LICENSE.rst

docs/license_link.rst

@@ -5,7 +5,7 @@ Intro
 -----
 
 
-QtNodes is a Qt5-based library designed for graphical representation of
+QtNodes is a Qt-based library designed for graphical representation of
 the node graphs and performing various operations on them.
 
 .. image:: /_static/calculator.png
@@ -25,10 +25,9 @@ The library could be used for two purposes:
   1. General-purpose graph visulalization and editing.
   2. Computing data in the nodes and propagating it through connections.
 
-The "headless" mode is also supported. It is possible to create,
-delete, connect and disconnect nodes, as well as propagate data,
-without assigning your :cpp:type:`AbstractGraphModel` derivative to a
-:cpp:type:`BasicGraphicsScene`.
+The "headless" mode is also supported. It is possible to create, delete, connect
+and disconnect nodes, as well as propagate data, without assigning your
+:cpp:type:`AbstractGraphModel` derivative to a :cpp:type:`BasicGraphicsScene`.
 
 Examples
 --------
@@ -40,29 +39,20 @@ The examples could be found in the folder ``examples``:
 - "legacy" examples from versions prior to ``3.0``:
 
   - ``text``. Text is propagated between the nodes.
-  - ``calculator``. Dataflow-based implementation of the simplest
+  - ``calculator/main.cpp``. Dataflow-based implementation of the simplest
     calculator. We use an advanced model
     :cpp:type:`QtNodes::DataFlowGraphModel` capable of storing the registry of
     NodeDataModel and propagating user data beween the nodes.
+  - ``calculator/headless_main.cpp``. The example loads a scene saved by a
+    GUI-based ``calculator`` example and computes several results without
+    creating any GUI elements.
   - ``connection_colors``. Demonstrates the ability to color the
     connections in correspondence to the connected data types.
-  - ``images``. Another dataflow example where images are propagated
-    between the nodes.
+  - ``resizable_images``. The examples shows how to embed a widget into nodes and
+    how to make the nodes resizable.
   - ``styles``. The example demonstrates graph style customization.
 
 
-TODOs
------
-
-1. Dynamic ports
-2.  `NodeGeometryDelegate`, `NodePaintDelegate`
-3. `ConnectionPaintDelegate`
-4. Python Wrapper using Shiboken
-5. Python examples
-6. Unit-Tests
-7. Documentation
-8. QML front-end
-
 
 Node Geometry
 -------------
@@ -97,16 +87,13 @@ Node Geometry
 
 
 
-Size is recalculated when
-^^^^^^^^^^^^^^^^^^^^^^^^^
+Node's size must be recalculated in following cases:
 
-0. After construction.
-1. Embedding the widget.
-2. After resizing.
-3. Before painting (conditional, depends on whether the font metrics
-   was changed).
-4. When incoming data changed (could trigger size changes, maybe in
-   captions).
-5. When embedded widget changes its size.
+  #. After construction.
+  #. Embedding the widget.
+  #. After resizing.
+  #. Before painting (conditional, depends on whether the font metrics was changed).
+  #. When incoming data changed (could trigger size changes, maybe in captions).
+  #. When embedded widget changes its size.
 
 

docs/overview.rst

@@ -0,0 +1 @@
+.. include:: ../README.rst

docs/readme_link.rst

@@ -1,2 +1,3 @@
 sphinx
 breathe
+breath_rtd_theme

docs/requirements.txt

@@ -1,12 +1,15 @@
-TODO
-====
+To Be Implemented
+=================
 
 
-- Save/restore to Json. Maybe inherit the GraphModel from Serializable.
-- Check how styles work and what needs to be done. See old
-  pull-requests.
-- Dynamic ports.
-- Python bindings.
-- QML front-end.
-- TESTS!
-- Website with documentation.
+- [✅ done] Save/restore to Json. Maybe inherit the GraphModel from Serializable
+- [➡️  work in progress] Vertical layout
+- [➡️  work in progress] Dynamic ports
+- [➡️  work in progress] Unit-Tests
+- [➡️  work in progress] Website with documentation
+- [⏸ not started] ``NodeGeometryDelegate``, ``NodePaintDelegate``
+- ``ConnectionPaintDelegate``
+- [⏸ not started] Check how styles work and what needs to be done. See old pull-requests
+- [☝ help needed] Python bindings. Maybe a wrapper using Shiboken
+  - Python examples
+- [☝ help needed] QML front-end

docs/todo.rst

@@ -60,13 +60,11 @@ class NodeGraphicsObject : public QGraphicsObject
   void
   moveConnections() const;
 
-
   /// Repaints the node once with reacting ports.
   void
   reactToConnection(ConnectionGraphicsObject const * cgo);
 
 protected:
-
   void
   paint(QPainter* painter,
         QStyleOptionGraphicsItem const* option,
@@ -100,12 +98,10 @@ class NodeGraphicsObject : public QGraphicsObject
   contextMenuEvent(QGraphicsSceneContextMenuEvent* event) override;
 
 private:
-
   void
   embedQWidget();
 
 private:
-
   NodeId _nodeId;
 
   AbstractGraphModel &_graphModel;

include/QtNodes/internal/NodeGraphicsObject.hpp

@@ -126,6 +126,7 @@ disconnect(PortType portToDisconnect) const
   ConnectionId incompleteConnectionId =
     makeIncompleteConnectionId(connectionId, portToDisconnect);
 
+  // Grabs the mouse
   auto const & draftConnection =
     _scene.makeDraftConnection(incompleteConnectionId);