WIP updating docs

CMakeLists.txt

@@ -40,7 +40,7 @@ add_custom_target(logo
     COMMAND
         ${CMAKE_COMMAND} -E env "PYTHONPATH=${AP_PYTHONPATH}"
             # Creates logo.{pdf,svg}
-            ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/source/script/ap_create_logo.py logo
+            ${Python3_EXECUTABLE} ${CMAKE_CURRENT_SOURCE_DIR}/environment/create_logo.py logo
 )
 
 add_custom_target(icon

README.md

@@ -5,3 +5,5 @@
 - [Developer manual](documentation/develop/index.rst)
 - [User manual](documentation/use/index.rst)
 - [Tester manual](documentation/test/index.rst)
+
+<img src="documentation/use/generator.png"/>

documentation/develop/example/README.rst

@@ -1,5 +1,6 @@
 Examples
 ========
-Some of the examples use io.StringIO to be able to treat a string as a file. When using
-``ap_plot_graphs`` to plot graphs, the name of a file can be passed containing similar content
-as shown in the examples.
+
+This section contains examples for plotting graphs using the ``adaptation_pathways``
+package. The same plots can be created by storing the information about the actions and sequences
+in a text- or binary-formatted dataset and using the ``ap_plot_graphs`` command.

documentation/develop/index.rst

@@ -7,8 +7,6 @@ Develop
    Development environment <environment>
    Create a release <release>
    Use of Git <git>
-   API <../api/modules>
-   Index <../genindex>
    Examples <example/index>
 
 

documentation/index.rst

@@ -7,6 +7,8 @@ Adaptation Pathways
 
    User manual <use/index>
    Developer manual <develop/index>
+   API <api/modules>
+   Index <genindex>
    Glossary <glossary>
    Changelog <changelog>
 

documentation/use/CMakeLists.txt

@@ -1,7 +1,10 @@
-foreach(name IN ITEMS index get_started)
-    configure_file(
-        ${name}.rst
-        ${name}.rst
-        COPYONLY
+foreach(name IN ITEMS
+        generator.png
+        generator.rst
+        get_started.rst
+        import_export.rst
+        index.rst
+        plot.rst
     )
+    configure_file(${name} ${name} COPYONLY)
 endforeach()

documentation/use/example/README.rst

@@ -1,2 +1,6 @@
 Examples
 ========
+
+This section contains examples for plotting pathway maps using the ``adaptation_pathways``
+package. The same plots can be created by storing the information about the actions and sequences
+in a text- or binary-formatted dataset and using the ``ap_plot_pathway_map`` command.

documentation/use/generator.rst

@@ -0,0 +1,21 @@
+Pathway Generator
+=================
+See also: :mod:`adaptation_pathways.cli.pathway_generator`
+
+The package contains a GUI application called ``ap_pathway_generator``. It can be used to
+interactively create pathways and save the results to a (binary) file.
+
+.. note::
+
+   The pathway generator is a proof of concept application. It proofs that the pathway plots
+   can be made part of an easy to install desktop application, made with Python. It is not
+   finished and not fool-proof yet. There are many things not working correctly or still missing.
+
+Example for starting the application and initializing it with information from a text- or
+binary-formatted dataset called ``my_pathways``.
+
+.. code-block:: bash
+
+   ap_pathway_generator my_pathways
+
+For help about the usage of the command type ``ap_pathway_generator --help``.

documentation/use/get_started.rst

@@ -1,7 +1,15 @@
 Get started
 ===========
 
-The software can be used by performing these steps in turn:
+Here, we assume that you want to get started using the ``adaptation_pathways`` Python package
+distributed as a so-called Python Wheel. There are other ways the package can be distributed,
+for example as a portable application, containing the Pathway Generator GUI application and all
+its dependencies. Installing that package is simply a matter of unzipping the file. The advantage
+is the simplicity to get the Pathway Generator application up and running, but to be able to
+use all functionality from the ``adaptation_pathways`` package, the Wheel should be installed
+as described on the rest of this page.
+
+The ``adaptation_pathways`` Python package can be used by performing these steps in turn:
 
 #. Create and activate a new virtual environment. There are multiple options for this. Below
    we show how to setup a virtual environment using Python's built-in venv module and using Conda.

documentation/use/import_export.rst

@@ -0,0 +1,85 @@
+Import and export
+=================
+
+The package contains two utilities for translating information about the pathways from text
+formats to a binary format and back: ``ap_import`` and ``ap_export``.
+
+
+Text format
+-----------
+
+Information about pathways can be stored in two text files, named ``<basename>-action.txt``
+and ``<basename>-sequence.txt``. The ``<basename>`` part can be replaced by any name that makes
+sense to you.
+
+``<basename>-action.txt``
+~~~~~~~~~~~~~~~~~~~~~~~~~
+This file contains columns with information about the actions:
+
+- name: string without spaces
+- colour: Information about the RGBA values, in hexadecimal format
+
+Example::
+
+    current #ff4c566a
+    a #ffbf616a
+    b #ffd08770
+    c #ffebcb8b
+
+Actions can be defined in terms of other actions (action combinations). This may have an
+influence on how such actions are visualized. The format for that is:
+``action(other_action1 & other_action2)``. For example, in the previous example, an action
+combination ``d`` could be added as follows::
+
+    d(a & b) #ffa3be8c
+
+
+``<basename>-sequence.txt``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+This file contains columns with information about the sequences of actions that together make
+up pathways:
+
+- from-action name: name of action from ``<basename>-action.txt``
+- to-action name: name of action from ``<basename>-action.txt``
+- tipping point: integer ≥ 0
+
+Example::
+
+    current     current 2030
+    current     a       2040
+    current     b       2050
+    a           c       2060
+
+To differentiate the same action in different pathways, action editions can be used. The format
+for that is: ``action[edition]``. For example, in the previous example, action ``c`` can also
+be used as a continuation of the sequence ``current b`` as follows::
+
+    b           c[2]    2070
+
+
+Import from text format to binary format
+----------------------------------------
+See also: :mod:`adaptation_pathways.cli.import_`
+
+Example for importing data from ``my_pathways-action.txt`` and ``my_pathways-sequence.txt`` to
+``my_pathways.apw``:
+
+.. code-block:: bash
+
+   ap_import my_pathways my_pathways
+
+For help about the usage of the command type ``ap_import --help``.
+
+
+Export from binary format to text format
+----------------------------------------
+See also: :mod:`adaptation_pathways.cli.export`
+
+Example for exporting data from ``my_pathways.apw`` to ``my_pathways-action.txt`` and
+``my_pathways-sequence.txt``:
+
+.. code-block:: bash
+
+   ap_export my_pathways my_pathways
+
+For help about the usage of the command type ``ap_export --help``.

documentation/use/index.rst

@@ -5,4 +5,9 @@ Use
    :maxdepth: 1
 
    Get started <get_started>
-   Examples <example/index>
+   Import / export <import_export>
+   Plotting pathways <plot>
+   Pathway generator <generator>
+
+
+.. image:: generator.png

documentation/use/plot.rst

@@ -0,0 +1,56 @@
+Plotting pathways
+=================
+
+.. toctree::
+   :maxdepth: 1
+
+   Examples <example/index>
+
+
+The package contains two command-line applications. One is called ``ap_plot_graphs`` and can
+be used to gain insight into various kinds of graphs used to store information about pathways,
+and one is called ``ap_plot_pathway_map`` and can be used to visualize pathway maps in the
+so-called :const:`CLASSIC <adaptation_pathways.plot.util.PathwayMapLayout.CLASSIC>` layout.
+
+
+``ap_plot_graphs``
+------------------
+See also:
+:mod:`adaptation_pathways.cli.plot_graphs`,
+:class:`SequenceGraph <adaptation_pathways.graph.sequence_graph.SequenceGraph>`,
+:class:`PathwayGraph <adaptation_pathways.graph.pathway_graph.PathwayGraph>`,
+:class:`PathwayMap <adaptation_pathways.graph.pathway_map.PathwayMap>`
+
+This command takes information about pathways as input, and outputs a plot of the sequence
+graph, a plot of the pathway graph and a plot of the pathway map in :const:`DEFAULT
+<adaptation_pathways.plot.util.PathwayMapLayout.DEFAULT>` layout.
+
+Example for creating plots from ``my_pathways-action.txt`` and ``my_pathways-sequence.txt``
+(or ``my_pathways.apw``) to ``./my_pathways-sequence_graph.pdf``,
+``./my_pathways-pathway_graph.pdf``, and ``./my_pathways-pathway_map.pdf``:
+
+.. code-block:: bash
+
+   ap_plot_graphs my_pathways .
+
+For help about the usage of the command type ``ap_plot_graphs --help``.
+
+
+``ap_plot_pathway_map``
+-----------------------
+See also:
+:mod:`adaptation_pathways.cli.plot_pathway_map`,
+:class:`PathwayMap <adaptation_pathways.graph.pathway_map.PathwayMap>`
+
+This command takes information about pathways as input, and outputs a single plot containing
+the pathway map in :const:`CLASSIC <adaptation_pathways.plot.util.PathwayMapLayout.CLASSIC>`
+layout.
+
+Example for creating a plot from ``my_pathways-action.txt`` and ``my_pathways-sequence.txt``
+(or ``my_pathways.apw``) to ``./my_pathways.pdf``:
+
+.. code-block:: bash
+
+   ap_plot_pathway_map my_pathways my_pathways.pdf
+
+For help about the usage of the command type ``ap_plot_pathway_map --help``.