Merge pull request #49 from compas-dev/update/doc-first-release

Update/Doc and the First Release

CHANGELOG.md

@@ -8,6 +8,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## Unreleased
 
 ### Added
+* Added `installation` documentation.
+* Added documentations: index, api, etc. Mockups style is improved.
 * Added `DeleteSelected` action class.
 * Added `DataType` as the data type template for generating the buffer.
 * Added `NetworkObject` for the scene objects.
@@ -45,6 +47,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * Added `NetworkObject`.
 
 ### Changed
+* The `Index` page.
+* Typing hints improved, now `compas_viewer` only support Python 3.9+.
 * Introduce decorator @lru_cache() to reduce duplicate calculations. 
 * Refactored the `Selector` and the instance_map structure, the main frame rate is higher and selection action is faster.
 * Fixed the bug of the `Selector`, drag selection is now more accurate.

docs/api/compas_viewer.components.rst

@@ -5,5 +5,5 @@ compas_viewer.components
 .. toctree::
     :maxdepth: 1
 
-    components/render
+    components/renderer
 

docs/api/components/render.rst → docs/api/components/renderer.rst

@@ -1,8 +1,8 @@
 *******************************************************************************
-compas_viewer.components.render
+compas_viewer.components.renderer
 *******************************************************************************
 
-.. currentmodule:: compas_viewer.components.render
+.. currentmodule:: compas_viewer.components.renderer
 
 Classes
 =======
@@ -11,14 +11,14 @@ Classes
     :toctree: ./generated
     :nosignatures:
 
-    Render
+    Renderer
     Camera
     Shader
     Selector
-    Render.mouseMoveEvent
-    Render.mousePressEvent
-    Render.mouseReleaseEvent
-    Render.wheelEvent
-    Render.keyPressEvent
-    Render.keyReleaseEvent
+    Renderer.mouseMoveEvent
+    Renderer.mousePressEvent
+    Renderer.mouseReleaseEvent
+    Renderer.wheelEvent
+    Renderer.keyPressEvent
+    Renderer.keyReleaseEvent
 

docs/api/index.rst

@@ -0,0 +1,67 @@
+
+********************************************************************************
+API Reference
+********************************************************************************
+
+This package provides a viewer for COMPAS.
+
+Viewer
+------
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.viewer
+
+
+Scene and Objects
+-----------------
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.scene
+
+
+Controller and Actions
+----------------------
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.controller
+    compas_viewer.actions
+
+
+Components and Configurations
+-----------------------------
+
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.components
+    compas_viewer.configurations
+
+
+Layout and UI
+--------------------
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.layout
+
+
+Utilities
+---------
+.. toctree::
+    :maxdepth: 1
+    :titlesonly:
+
+    compas_viewer.utilities
+
+

docs/conf.py

@@ -2,7 +2,6 @@
 # -*- coding: utf-8 -*-
 
 import sphinx_compas2_theme
-
 from sphinx.writers import html
 from sphinx.writers import html5
 
@@ -77,10 +76,9 @@ def setup(app):
 plot_formats = ["png"]
 
 # intersphinx options
-
 intersphinx_mapping = {
     "python": ("https://docs.python.org/", None),
-    "compas": ("https://compas.dev/compas/latest/", None)
+    "compas": ("https://compas.dev/compas/latest/", None),
 }
 
 # linkcode
@@ -89,16 +87,21 @@ def setup(app):
 
 # extlinks
 
-extlinks = {}
+extlinks = {
+    "GL": ("https://pyopengl.sourceforge.net/documentation/manual-3.0/%s.html", "%s"),
+    "QtCore": ("https://doc.qt.io/qtforpython-6/PySide6/QtCore/Qt.html#PySide6.QtCore.%s", "%s"),
+    "PySide6": ("https://doc.qt.io/qtforpython-6/%s.html", "%s"),
+    "compas": ("https://compas.dev/compas//latest/api/%s.html", "%s"),
+}
 
 # from pytorch
 
 sphinx_compas2_theme.replace(html.HTMLTranslator)
 sphinx_compas2_theme.replace(html5.HTML5Translator)
 
 # -- Options for HTML output ----------------------------------------------
-
-html_theme = "sidebaronly"
+html_sidebars = {"index": []}
+html_theme = "multisection"
 html_title = project
 
 favicons = [
@@ -109,6 +112,9 @@ def setup(app):
 ]
 
 html_theme_options = {
+    "external_links": [
+        {"name": "COMPAS Framework", "url": "https://compas.dev"},
+    ],
     "icon_links": [
         {
             "name": "GitHub",
@@ -138,6 +144,7 @@ def setup(app):
         "image_dark": "_static/compas_icon_white.png",  # relative to parent of conf.py
         "text": project,
     },
+    "navigation_depth": 2,
 }
 
 html_context = {

docs/examples.rst → docs/examples/index.rst

@@ -1,10 +1,11 @@
+
 ********************************************************************************
 Examples
 ********************************************************************************
 
 .. toctree::
-   :maxdepth: 2
-   :titlesonly:
-   :glob:
+    :maxdepth: 1
+    :titlesonly:
+    :caption: Basic Examples
 
-   examples/basics
+    basics

docs/index.rst

@@ -1,33 +1,70 @@
+:html_theme.sidebar_secondary.remove: true
+
 ********************************************************************************
-compas_viewer
+COMPAS Viewer
 ********************************************************************************
-
 .. rst-class:: lead
 
-Standalone viewer for COMPAS
+Standalone viewer for COMPAS 2.0 with features:
+
 
-.. .. figure:: /_images/
+* **Fully COMPAS Support**: Full support for all :compas:`compas.geometry`  (primitives, shapes, network, mesh, assembly, model, etc.) based on :compas:`compas.scene` structure ...
+* **Universal Architecture**: Full support Mac, Windows, and Linux with Python 3.9+. More various platforms are coming soon ...
+* **Installation Friendly**: Depend only on COMPAS, OpenGL and PySide6. Installation with pip is fast and easy ...
+* **Flexible Customization**: Flexible customize your own UI layout with buttons, render display with colors, action with keyboard preferences ...
+* **Data-driven Visualization**: Visualize your assembly data, mesh data, network data, and more with :compas:`compas.datastructures` ...
+* **Easy-to-use Interaction**: Action-based interaction with mouse and keyboard, and easy-to-use API for your own interaction ...
+
+.. figure:: /_images/PLACEHOLDER.png
      :figclass: figure
      :class: figure-img img-fluid
 
+Installation
+============
+
+.. toctree::
+	:maxdepth: 1
+	:titlesonly:
+
+	installation
+
 
-Table of Contents
-=================
+Tutorials
+=========
 
 .. toctree::
-   :maxdepth: 3
-   :titlesonly:
+	:maxdepth: 2
+	:titlesonly:
+
+	tutorials/index
+
+
+Examples
+========
+
+.. toctree::
+    :maxdepth: 2
+    :titlesonly:
+
+    examples/index
+
+
+API Reference
+=============
+
+.. toctree::
+    :maxdepth: 2
+
+    api/index
 
-   Introduction <self>
-   installation
-   tutorials
-   examples
-   api
-   license
+History
+=======
+COMPAS Viewer is the next generation of :mod:`compas_view2` which is beased on the 1.0 version of :mod:`compas`.
+Experiencing years' iteraions, this new version of COMPAS Viewer is stabliy designed for wider senarios and use cases.
 
 
 Indices and tables
 ==================
 
 * :ref:`genindex`
-* :ref:`modindex`
+* :ref:`search`

docs/installation.rst

@@ -1,3 +1,33 @@
 ********************************************************************************
 Installation
 ********************************************************************************
+COMPAS Viewer can be easily installed on multiple platforms, using popular package managers such as conda or pip.
+
+If you don't have COMPAS installed
+===================================
+Check out the COMPAS installation instructions at https://compas.dev/compas/latest/userguide/installation.html
+
+If you have COMPAS installed
+============================
+Activate your COMPAS environment and install COMPAS Viewer from `pip`.
+
+.. code-block:: bash
+
+    pip install compas_viewer
+
+Verify the installation
+=======================
+COMPAS Viewer can be simply lunched by the following command in your terminal:
+
+.. code-block:: bash
+
+    python -m compas_viewer
+
+Update with pip
+===============
+Update COMPAS Viewer to the latest version with pip.
+
+.. code-block:: bash
+
+    pip install --upgrade compas_viewer
+

docs/tutorials/configurations.rst

@@ -0,0 +1,15 @@
+********************************************************************************
+File Structure
+********************************************************************************
+
+.. ::`compas_viewer` reads its customized ::`.viewer` file. The file architecture is designed for better data exchange, collaboration, and communication.
+
+.. Concept
+.. ===========
+
+.. 1. **Folder-based** :  ::`.viewer` file is a `.zip` folder (archive) that contains files in various formats.
+
+.. 2. **Extendability** :  ::`.viewer` file could contain any type of files. The core functions of viewer are `.json` based and the invoking functions are dictionary-find based, meaning that only missing parameters will cause the loading failure while redundant parameters will only be ignored.
+
+.. Quick Look
+.. ==========