gdt050579 · rzaharia · Mar 15, 2026 · Mar 15, 2026
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -11,8 +11,8 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v1
-    # Standard drop-in approach that should work for most people.
+    - uses: actions/checkout@v4
+    # Build Sphinx docs from docs/ and publish to gh-pages.
     - uses: ammaraskar/sphinx-action@master
       with:
         docs-folder: "docs/"

diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -1,2 +1,2 @@
-sphinx
-sphinx-rtd-theme
+sphinx>=5.0,<8
+sphinx-rtd-theme>=1.2,<3
diff --git a/docs/source/_templates/.gitkeep b/docs/source/_templates/.gitkeep
diff --git a/docs/source/architecture.rst b/docs/source/architecture.rst
@@ -1,2 +1,70 @@
 GView architecture
-===================
+==================
+
+Architecture flow
+-----------------
+
+1. **Content type** — Determine whether the content is binary or textual. For text,
+   detect encoding and decode to a standardized format (e.g. UTF-16).
+
+2. **Plugin selection** — Search available data identifier (Type) plugins for one that
+   can interpret the data. If none matches, fall back to a generic plugin that only
+   distinguishes binary vs. text.
+
+3. **Viewers and extraction** — The chosen Type plugin selects suitable smart viewers.
+   Users can switch viewers and use them to extract artifacts or data from the content.
+
+4. **Iteration** — Repeat steps 1–3 for extracted components, using artifacts from
+   previous steps to drive further analysis.
+
+Directory structure
+-------------------
+
+::
+
+   GView/
+   ├── AppCUI/              # UI framework (subproject, separate repo)
+   ├── GViewCore/           # Core library
+   │   ├── include/
+   │   │   └── GView.hpp    # Public API for plugins
+   │   └── src/
+   │       ├── include/Internal.hpp
+   │       ├── App/         # Application logic, dialogs
+   │       ├── View/        # Smart viewers (Buffer, Text, Lexical, Image, Grid, Dissasm, Container)
+   │       ├── Utils/       # DataCache, ZonesList, ErrorList, etc.
+   │       ├── Hashes/      # Hash implementations
+   │       ├── Decoding/    # Base64, ZLIB, etc.
+   │       ├── DigitalSignature/
+   │       ├── Dissasembly/ # Capstone wrapper
+   │       ├── Security/    # Restricted mode, crypto
+   │       └── Type/        # Plugin loading and type matching
+   ├── GView/               # Main executable
+   ├── Types/               # Type plugins (PE, ELF, MACHO, PDF, PCAP, ZIP, CSV, etc.)
+   ├── GenericPlugins/      # Generic plugins (Hashes, EntropyVisualizer, Dropper, SyncCompare, Unpacker, etc.)
+   ├── cmake/
+   ├── docs/
+   └── build/ / bin/
+
+Code structure
+--------------
+
+* **GViewCore** — Core library: application logic, smart viewers, hashes, decoding,
+  digital signatures, disassembly, plugin loading. Plugins use only ``GView.hpp``.
+* **GView** — Main executable.
+* **Types/** — Type-specific plugins (PE, ELF, Mach-O, PDF, PCAP, ZIP, CSV, INI, JS, etc.).
+* **GenericPlugins/** — Generic plugins (Hashes, EntropyVisualizer, Dropper, SyncCompare,
+  Unpacker, CharacterTable, FileDownloader).
+* **AppCUI** — Terminal UI framework (subproject).
+
+Diagrams
+--------
+
+High-level architecture:
+
+.. image:: _static/GView.svg
+   :alt: GView high-level architecture
+
+Core (GViewCore) architecture:
+
+.. image:: _static/GViewCore.svg
+   :alt: GViewCore architecture
diff --git a/docs/source/character_table.rst b/docs/source/character_table.rst
@@ -0,0 +1,5 @@
+Character table
+===============
+
+Generic plugin for viewing and inspecting character tables and code pages.
+Details to be added.
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -72,7 +72,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -198,4 +198,6 @@
 
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3/', None),
+}
diff --git a/docs/source/configuration.rst b/docs/source/configuration.rst
@@ -5,15 +5,15 @@ GView is configured via ``GView.ini`` file (that should be located next to GView
 
 The following section should be seen in a ``GView.ini`` file:
 
-* ``[GView]`` - a section with the general configuration for GView. Tipically it contains associated key for changing the view, cache size, etc.
+* ``[GView]`` - a section with the general configuration for GView. Typically it contains associated key for changing the view, cache size, etc.
 * ``[AppCUI]`` - a section with the general configuration for AppCUI framework (color, frontend, etc)
 * ``[Type.<XXX>]`` - various sections that describe characteristics of each supported type in GView
 * ``[View.<xxx>]`` - various section for each smart view
 
 Types
 -----
 
-A ``[Type.xxx]``` section usually contains the following:
+A ``[Type.xxx]`` section usually contains the following:
 
 * a `Description` field that explains the type of the plugin
 * a `Extension` field that can be a simple string or a list of strings containing the list of extensions associated with this field.
@@ -37,7 +37,7 @@ A ``[Type.xxx]``` section usually contains the following:
 | Rule             | Type    | Usage                                            | Example                        |
 +==================+=========+==================================================+================================+
 | magic            | Binary  | Identifies a binary magic from the start of the  | **magic**:FF 20 30             |
-|                  | Files   | file. A magic must be foollowed by a list of hex |                                |
+|                  | Files   | file. A magic must be followed by a list of hex  |                                |
 |                  |         | values separated with spaces                     |                                |
 +------------------+---------+--------------------------------------------------+--------------------------------+
 | startswith       | Text    | Checks if a file starts with a specific text     | **startswith**:#include        |
@@ -57,6 +57,6 @@ A ``[Type.xxx]``` section usually contains the following:
 
   ..  code-block:: ini
 
-      Pattern = ["startswith:ABC","linestartswith:test"] ; identifies a text file where either the firs line starts with `ABC`  
+      Pattern = ["startswith:ABC","linestartswith:test"] ; identifies a text file where either the first line starts with `ABC`  
                                                          ; or there is a line within the first 10 lines that starts with `test`
 
diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
@@ -1,2 +1,36 @@
 GView contributing
-===================
+==================
+
+Start contributing
+------------------
+
+1. **Clone with submodules**::
+
+      git clone --recurse-submodules <your-repo-link>/GView.git
+
+2. **Build** — Use CMake and vcpkg as described in :doc:`usage`. Enable tests with
+   ``-DENABLE_TESTS=ON``.
+
+3. **Documentation** — Sphinx sources are under ``docs/``. Install tooling::
+
+      pip install -r docs/requirements.txt
+
+   Build HTML docs::
+
+      cd docs && make html
+
+   Output is in ``docs/build/html``.
+
+4. **Code style** — Follow the project's C++20 conventions: ``PascalCase`` for types
+   and functions, ``camelCase`` for variables. Use only the public API in
+   ``GViewCore/include/GView.hpp`` for plugin development. See :doc:`plugin_development`
+   for the plugin contract, patterns, and conventions.
+
+5. **Pull requests** — Open PRs against ``main``. CI runs on push and on pull requests;
+   ensure builds and tests pass.
+
+Reporting issues
+----------------
+
+Use the repository issue tracker for bugs and feature requests. Check existing issues
+and use the provided templates when possible.
diff --git a/docs/source/core.rst b/docs/source/core.rst
@@ -1,20 +1,22 @@
 GView Core
-===================
+==========
 
 Core
------------------
+----
 
-// TODO:
+This section covers internal and format-specific details used by GViewCore and
+various Type plugins. Content is expanded over time.
 
-Golang
------------------
-https://go.dev/src/runtime/symtab.go
-https://go.dev/src/runtime/runtime2.go
-https://github.com/0xjiayu/go_parser/blob/master/pclntbl.py
-https://github.com/strazzere/golang_loader_assist/blob/master/golang_loader_assist.py#L200
-https://www.freebuf.com/articles/others-articles/176803.html
-https://gist.github.com/matteobertozzi/1521947
-https://docs.google.com/document/d/1lyPIbmsYbXnpNj57a261hgOYVpNRcgydurVQIyZOz_o/pub
-https://github.com/dutchcoders/jupyter-radare2/blob/master/Annotating%20Go%20Binaries%20using%20Cutter.ipynb
-https://go.dev/src/debug/gosym/pclntab.go
-https://www.mandiant.com/resources/golang-internals-symbol-recovery
+Golang binary support (references)
+------------------------------------
+
+Type plugins (e.g. PE, ELF, Mach-O) use the following references for Go symbol and
+runtime parsing:
+
+* `Go runtime symtab <https://go.dev/src/runtime/symtab.go>`__
+* `Go runtime2 <https://go.dev/src/runtime/runtime2.go>`__
+* `gosym/pclntab <https://go.dev/src/debug/gosym/pclntab.go>`__
+* `go_parser pclntbl <https://github.com/0xjiayu/go_parser/blob/master/pclntbl.py>`__
+* `golang_loader_assist <https://github.com/strazzere/golang_loader_assist>`__
+* `Mandiant: Golang internals - symbol recovery <https://www.mandiant.com/resources/golang-internals-symbol-recovery>`__
+* `Go binaries in Cutter <https://github.com/dutchcoders/jupyter-radare2>`__
diff --git a/docs/source/description.rst b/docs/source/description.rst
@@ -1,2 +1,39 @@
 GView description
-===================
+=================
+
+General description
+-------------------
+
+**GView** is a powerful tool for examining files or any data with a defined structure,
+such as buffers or memory zones. Users can leverage the diverse range of available
+visualization options to effectively analyze and interpret the information.
+
+From a developer perspective, GView offers a flexible platform to create plugins that
+parse various data structures. Developers can create customized views and enhance
+analysis capabilities by writing Type plugins (for specific file formats) or Generic
+plugins (for operations that apply to any file).
+
+Use cases
+---------
+
+* Malware analysis and incident response
+* File format reverse engineering
+* Network traffic analysis (PCAP)
+* Binary executable analysis (PE, ELF, Mach-O)
+* Document forensics (PDF, DOC, EML)
+* Archive inspection (ZIP, ISO)
+
+See GView in action
+-------------------
+
+**Scenario 1: Malicious infection**
+A screencast shows how GView can analyze the contents of a compromised system. By
+examining network traffic, security analysts can uncover how malicious actors gained
+unauthorized access. GView's visualization helps identify suspicious hints and
+understand the attack's impact. (`Open video <https://youtu.be/Z1nTRKPewCg>`__)
+
+**Scenario 2: Suspicious email**
+GView is used to analyze the impact of a breach after a victim has been infected.
+The cause was a suspicious email. By analyzing email headers, attachments, and
+embedded content, analysts can uncover hidden malicious code or phishing attempts.
+(`Open video <https://youtu.be/LpsvcgCkII8>`__)
diff --git a/docs/source/development.rst b/docs/source/development.rst
@@ -1,10 +1,20 @@
 GView development
-===================
+=================
 
-Github workflows
------------------
+Testing
+-------
 
-Github workflows will be automatically triggered on push to ``main`` and on ``pull_request``.
+* Tests are enabled with ``-DENABLE_TESTS=ON`` at configure time.
+* Unit tests are in files matching ``**/tests_*.cpp``.
+* The testing build produces a ``GViewTesting`` executable instead of ``GView``.
+* The ``run_core_tests()`` macro from ``cmake/core_testing.cmake`` is used to
+  register test sources.
 
-If any workflows need to be triggered for other branches, one could create a draft PR to start testing or manually trigger the workflows from the `Actions` page, while selecting the required workflow. 
-The contributor will be greeted with a ``This workflow has a workflow_dispatch event trigger`` and a ``Run workflow`` button.
+Run the test executable from your build directory after building with tests enabled.
+
+GitHub workflows
+----------------
+
+Workflows run on push to ``main`` and on ``pull_request``. To run them for other
+branches, create a draft PR or trigger manually from the Actions page: choose the
+workflow and use **Run workflow** when it has a ``workflow_dispatch`` trigger.