First version of the documentation (english only).

conf.py

@@ -54,9 +54,21 @@
 #
 html_theme = 'sphinx_rtd_theme'
 
+# These paths are either relative to html_static_path
+# or fully qualified paths (eg. https://...)
+html_css_files = [
+    'css/custom.css',
+]
+
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['static']
 
-html_logo = 'static/degate_small.png'
+html_logo = 'static/degate_small.png'
+
+html_theme_options = {
+    "navigation_depth": 4,
+    "collapse_navigation": False,
+    "sticky_navigation": False,
+}

index.rst

@@ -18,7 +18,8 @@ __ https://gitter.im/DegateCommunity/Degate
 __ https://github.com/DorianBDev/
 
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 5
    :caption: Contents:
 
-   pages/introduction
+   pages/introduction
+   pages/general

pages/general.rst

@@ -0,0 +1,20 @@
+General
+==================================
+
+You will find here general documentation about workspace elements.
+
+Logic model
+~~~~~
+
+The logic model represents the electrical logic of the project, where the majority of your work will be on. It's directly linked to the reconstruction of the netlist, which will pass by creating a list of used gates (with a behaviour defined, in Verilog for example), finding gate instances and interconnecting all electrical objects to then be able to retrieve the full netlist and be able to export it.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   general_dir/annotation
+   general_dir/subproject
+   general_dir/emarker
+   general_dir/gate
+   general_dir/via
+   general_dir/wire

pages/general_dir/annotation.rst

@@ -0,0 +1,8 @@
+Annotation
+==================================
+
+An annotation is a block with a text line that can be used to annotate/highlight a region of interest.
+
+.. image:: images/annotation.png
+  :alt: Degate annotation
+

pages/general_dir/emarker.rst

@@ -0,0 +1,9 @@
+EMarker
+==================================
+
+An EMarker is a general connectable electrical object, it representation of an electrically connectable marker object. It can represent any non-available electrical object in Degate (it's barely a placeholder).
+
+.. image:: images/emarker.png
+  :alt: Degate EMarker
+
+You can set these properties for a EMarker : a name, a description, if the EMarker is a module port and a fill color. To set an EMarker diameter, see the project settings dialog (from the "Project" submenu of the top bar).

pages/general_dir/gate.rst

@@ -0,0 +1,58 @@
+Gate
+==================================
+
+There are two separate concepts involving gates : gate instances and gate templates.
+
+.. image:: images/gates.png
+  :alt: Degate gates
+
+Gate templates
+--------------
+
+A gate template represents a gate type (like an inverter, a flip-flop...) that can be analysed, had a specific behaviour (coded in VHDL for example) and be reused and instantiated somewhere else. A gate instance (what appears in the workspace) is always derived from a gate template.
+
+You can access a list of gate templates with the gate library dialog available in the toolbar or in the "Gate" submenu of the top bar.
+
+.. image:: images/gate_library.png
+  :alt: Degate gate library
+
+Gate instances
+--------------
+
+A gate instance is a representation of a physical implementation of a gate template. To create a gate instance, you always need to have the corresponding gate template already created.
+
+.. image:: images/gate_list.png
+  :alt: Degate gate list
+
+Gate edit
+--------------
+
+You can edit a gate instance (or a gate template from the gate library) by double clicking on it or by using the "Edit selected" from the "Gate" submenu of the top bar. In it, you will find three tabs : entity, behaviour and layout.
+
+Entity tab
+~~~~~
+
+The entity tab will let you edit basic information about the gate template like colors, name, description, ports...
+
+.. image:: images/gate_edit_entity.png
+  :alt: Degate gate edit dialog entity tab
+
+Behaviour tab
+~~~~~
+
+The behaviour tab will let you set the logic behind a gate, his behaviour. You can set it with free text, in VHDL or in Verilog. You will then be able to compile and test it with gtkwave (for Verilog only).
+
+Also, when the behaviour is set, you can export it when it's inside a module, and if the module is the project top level module, it will export the whole netlist.
+
+.. image:: images/gate_edit_behaviour.png
+  :alt: Degate gate edit dialog behaviour tab
+
+.. warning:: You can only export a module in Verilog so, if you want to be able to export the whole netlist, use Verilog to set gate instances behaviour.
+
+Layout tab
+~~~~~
+
+The layout tab will show you images of a gate instance for the gate template that's being edited on one metal layer (if set), one logic layer (mandatory, so always set) and one transistor layer (if set).  
+
+.. image:: images/gate_edit_layout.png
+  :alt: Degate gate edit dialog layout tab

pages/general_dir/subproject.rst

@@ -0,0 +1,17 @@
+Subproject
+==================================
+
+A subproject is a clickable annotation, with a double click you can close and save the current project and open the concerned subproject.
+
+.. image:: images/subproject.png
+  :alt: Degate subproject
+
+Create subproject
+-----
+
+To create a subproject, you need to select an area with the right click, go to the "Project" submenu of the top bar, and click on "Create a subproject from selection".
+
+.. image:: images/subproject_creation.png
+  :alt: Degate subproject creation
+
+Then, it will ask you to create a new project, as presented in a previous page (even if it's a subproject).

pages/general_dir/via.rst

@@ -0,0 +1,16 @@
+Via
+==================================
+
+A via is an electrical connectable object that will represent an electrical connection between two adjacent layers.
+
+.. image:: images/via_1.png
+  :alt: Degate via
+
+To create a via, you can right click to open the context menu, and select "Create new via". To connect two vias, you need to electrically interconnect them (by switching layers and CTRL + Right click to select them).
+
+You can also connect a via to other objects (like ports or wires...).
+
+.. image:: images/via_2.png
+  :alt: Degate follow via
+
+You can follow a connected via to go to the interconnected layer, by right clicking and selecting the "Follow via" option in the context menu.

pages/general_dir/wire.rst

@@ -0,0 +1,15 @@
+Wire
+==================================
+
+You can create a wire, that is a connectable electrical object, with the wire tool and by right clicking and moving the mouse.
+
+.. image:: images/wire_tool.png
+  :alt: Degate wire tool
+  :width: 80
+
+By default, each new wire first point will be the end of the previous one. To reset the wire tool, right click to open the context menu and click on "Reset wire tool".
+
+.. image:: images/wire.png
+  :alt: Degate wire
+
+You should limit the number of wires to keep the workspace clean, for example, if a wire connects two gate ports, just interconnect them and avoid creating an intermediate wire.

pages/introduction.rst

@@ -1,3 +1,15 @@
 Introduction
 ==================================
 
+You will find below a list of topics that will present basic functionalities of Degate.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   introduction_dir/create_project
+   introduction_dir/matching
+   introduction_dir/modules
+   introduction_dir/rule_violations
+   introduction_dir/shortcuts
+   introduction_dir/window

pages/introduction_dir/create_project.rst

@@ -0,0 +1,47 @@
+Create a new project
+==================================
+
+.. note:: The **old Degate** was using a size based project system, with a static project size defined during project creation. This meant inability to change the size after the project creation, even when you add a larger image than previously planned (so, with the old Degate, you had to recreate the project 'from scratch'). The **new Degate** uses a different system, you no longer have to worry about the project size during creation, you just need to provide at least one layer with a valid image.
+
+Images alignment
+--------------
+
+A Degate project needs only **layer images** to start. They will be the core of the project and the core of the process to recover the netlist (or a part of it). However there is some condition that you need to take care before creating the project (you can reimport layer images after the project creation, so no worries):
+
+- The layer images need to be aligned (they must be able to overlap correctly).
+- The layer images need to have the same overall quality (this is not mandatory, but if they are not of the same quality, you will have pain to align them).
+
+.. warning:: **Very important**: Degate has (for the moment) no built-in tools to align layer images, you have to do this downstream.
+
+To align these layer images, you have to consider that Degate cannot shift them, they will be open directly and placed in 0,0 (upper left corner). So, if these layer images are not aligned from the upper left corner, there will be an offset between the layers.
+
+Project creation dialog
+--------------
+
+You can access the project creation dialog from the "Project" tabs of the top menu, and by pressing the "New" button of this submenu. You will arrive on this window:
+
+.. image:: images/project_creation_dialog.png
+  :alt: Project creation dialog image
+
+With this dialog, you will be able to set the project name, the project directory path and the project layers. The project directory path is the directory where the project directory will be created. You will need at least one valid layer with an image set. To add a layer, you need to click on the "+" button. After that, a new layer will appear where you can set the state (if disabled, you will not see it inside the workspace, this can be changed anytime), the description, the type and the image.
+
+The type of a layer can be of these 4 types:
+
+- **Undefined**: undefined layer (useful if you want to start the analysis later).
+- **Metal**: interconnection layer (M1, M2 M...).
+- **Logic**: the layer where you will define gates.
+- **Transistor**: transistor layer.
+
+To learn more about these types, please see the Layman's Guide to IC Reverse Engineering `here <http://siliconzoo.org/tutorial.html>`_.
+
+To set the background image, you need to click on the red button, it will open a new dialog to select an image to import. After that done, you just need to click on "Ok" to validate and wait during the image(s) importation.
+
+.. image:: images/project_creation_dialog_completed.png
+  :alt: Completed project creation dialog image
+
+After clicking "Ok" you will get a loading dialog:
+
+.. image:: images/project_creation_dialog_completed_loading.png
+  :alt: Loading phase of the completed project creation dialog image
+
+Well done ! Your project is now created and loaded.

pages/introduction_dir/matching.rst

@@ -0,0 +1,69 @@
+Matching
+==================================
+
+To start a "matching phase" you firstly need to select an area (by holding the right click) to define the area used to match templates, vias or wires. This is optional, if you don't select an area, the whole project size will be used. Also, please note that the "matching phase" will use the current selected/active layer.
+
+You can access the different "matching phase" types in the "Matching" top bar submenu.
+
+Template matching
+-----
+
+Template matching will automatically detect gate template inside an area. After selecting the area, select "Template matching" in the "Matching" top bar submenu. You will then fall on this dialog:
+
+.. image:: images/template_matching_select.png
+  :alt: Degate template matching gate template select dialog
+
+You need to select the desired gate(s) template to match (you need at least one). Then, you will fall on this dialog:
+
+.. image:: images/template_matching.png
+  :alt: Degate template matching dialog
+
+To start the template matching phase, you can adjust different options, which are:
+
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Option name                            | Meaning                                                                                                                                                                                                                       |
++========================================+===============================================================================================================================================================================================================================+
+| Threshold to start hill climbing       | The threshold to start looking for a gate template. If the value is low, it will take more time to complete.                                                                                                                  |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Threshold for detection                | The threshold to confirm the detection of a gate template. If the value is low, it will take more time to complete. This value should be greater than the one above.                                                          |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Scale image down by factor             | The scaled version of the image to use during the detection. The more the image will be scaled down, the more the time to complete will be low.                                                                               |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Max step size for search after scaling | If the value is low (1 pixel minimum), it will take more time to complete, but will be more accurate. This value depends on the scaled version of the image (if the image is very scaled, it's better to use a value near 1). |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Match template orientation(s)          | Orientation(s) to search for a gate template. For example, if you select only the normal orientation, if there is the same gate template but flipped, it will not match.                                                      |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| Match template type                    | Detect for gate template along grid columns or rows. If no grid is available, it will not use any grid.                                                                                                                       |
++----------------------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+After running the template matching, you will obtain a dialog with the results of the detection phase, like that:
+
+.. image:: images/template_matching_end.png
+  :alt: Degate template matching end dialog
+
+Via matching
+-----
+
+Via matching in Degate will take all already placed vias as reference (need at least 1), and will use them to match new one(s) with the same layout. After selecting (or not) the matching area, you can access via matching by selecting "Via matching" in the "Matching" top bar submenu. You will then fall on this dialog:
+
+.. image:: images/via_matching.png
+  :alt: Degate via matching dialog
+
+To start the via matching phase, you can adjust different options, which are:
+
++-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| Option name             | Meaning                                                                                                                                       |
++=========================+===============================================================================================================================================+
+| Threshold for detection | The threshold to detect a via, a higher value will only keep the most matching vias. If the value is low, it will take more time to complete. |
++-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| Via diameter            | The via diameter to match (default is the project default via diameter value).                                                                |
++-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+| Max vias to match       | Max number of vias to match, it can be useful when you are not sure of your parameters values.                                                |
++-------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------+
+
+Wire matching
+-----
+
+.. warning:: Wire matching is a "broken" feature of Degate, it's not working well. However, you can try to use it keeping in mind that this functionality get some limitations.
+
+We will not document this part of Degate due to the warning above, and because it will be completely rewritten shortly.

pages/introduction_dir/modules.rst

@@ -0,0 +1,18 @@
+Modules
+==================================
+
+Modules are a way to organize your logic model into separate groups and export them (in Verilog language). You always have a top level module, if you want to export your project in Verilog, export the top level module (the one with the project name).
+
+.. image:: images/modules.png
+  :alt: Project modules dialog
+
+A module can be a child of another one, and every module is the main module child. You can move gates into modules, inside the module dialog or in the workspace with the "Logic" top bar submenu. All gates are, by default, in the project module (top level one).
+
+In this dialog you can find 3 panels, one is the module one, where you can create or remove modules, set a type or export in Verilog. The second one, will show all gates of the selected module. You can move them into another module or jump to them into the workspace. The last panel will show all module ports.
+
+.. warning:: You can only export a module in Verilog.
+
+Module port
+-----
+
+A module port is an object connected with other objects (at least one) that are not part of this module.