restruct documentation

GAMS-dev · Oct 23, 2023 · 59d7b1d · 59d7b1d
1 parent d14cd68
commit 59d7b1d
Show file tree

Hide file tree

Showing 21 changed files with 41 additions and 97 deletions.
diff --git a/+gams/+transfer/Alias.m b/+gams/+transfer/Alias.m
@@ -47,7 +47,6 @@
 %
 % See also: gams.transfer.Set, gams.transfer.Container
 
-%> @ingroup symbol
 %> @brief GAMS Alias
 %>
 %> This class represents a GAMS Alias, which is a link to another GAMS \ref

diff --git a/+gams/+transfer/Container.m b/+gams/+transfer/Container.m
@@ -67,13 +67,12 @@
 % gams.transfer.Variable, gams.transfer.Equation
 %
 
-%> @ingroup container
 %> @brief GAMS Transfer Container stores (multiple) symbols
 %>
 %> A GAMS GDX file is a collection of GAMS symbols (e.g. variables or
 %> parameters), each holding multiple symbol records. In GAMS Transfer the
 %> Container is the main object that holds different symbols and allows to read
-%> and write those to GDX. See \ref gams_transfer_matlab_container for more
+%> and write those to GDX. See \ref GAMS_TRANSFER_MATLAB_CONTAINER for more
 %> information.
 %>
 %> **Indexed Mode:**

diff --git a/+gams/+transfer/DomainViolation.m b/+gams/+transfer/DomainViolation.m
@@ -47,7 +47,6 @@
 % See also: gams.transfer.Set, gams.transfer.Symbol
 %
 
-%> @ingroup records
 %> @brief Domain Violation
 %>
 %> Domain violations occur when a symbol uses other \ref gams::transfer::Set

diff --git a/+gams/+transfer/Equation.m b/+gams/+transfer/Equation.m
@@ -65,7 +65,6 @@
 % See also: gams.transfer.Container, gams.transfer.EquationType, gams.transfer.Set
 %
 
-%> @ingroup symbol
 %> @brief GAMS Equation
 %>
 %> **Example:**

diff --git a/+gams/+transfer/EquationType.m b/+gams/+transfer/EquationType.m
@@ -37,7 +37,6 @@
 % See also: gams.transfer.Equation
 %
 
-%> @ingroup symbol
 %> @brief GAMS Equation Types
 %>
 %> This class holds the possible GAMS equation types similar to an enumeration

diff --git a/+gams/+transfer/Parameter.m b/+gams/+transfer/Parameter.m
@@ -63,7 +63,6 @@
 % See also: gams.transfer.Container, gams.transfer.Set
 %
 
-%> @ingroup symbol
 %> @brief GAMS Parameter
 %>
 %> **Example:**

diff --git a/+gams/+transfer/RecordsFormat.m b/+gams/+transfer/RecordsFormat.m
@@ -35,7 +35,6 @@
 % compatibility (e.g. for Octave).
 %
 
-%> @ingroup records
 %> @brief GAMS Transfer Records Formats
 %>
 %> This class holds the possible GAMS Transfer formats of records similar to

diff --git a/+gams/+transfer/Set.m b/+gams/+transfer/Set.m
@@ -65,7 +65,6 @@
 % See also: gams.transfer.Container
 %
 
-%> @ingroup symbol
 %> @brief GAMS Set
 %>
 %> **Example:**

diff --git a/+gams/+transfer/SpecialValues.m b/+gams/+transfer/SpecialValues.m
@@ -38,7 +38,6 @@
 % (NaN, Inf and -Inf, respectively), NA and EPS do not. The latter two are
 % therefore mapped to a special NaN and -0, respectively.
 
-%> @ingroup records
 %> @brief GAMS Special Values
 %>
 %> GAMS GDX offers five special values: \ref gams::transfer::SpecialValues::NA

diff --git a/+gams/+transfer/Symbol.m b/+gams/+transfer/Symbol.m
@@ -36,7 +36,6 @@
 % gams.transfer.Variable, gams.transfer.Equation
 %
 
-%> @ingroup symbol
 %> @brief GAMS Symbol (Set, Alias, Parameter, Variable or Equation)
 %>
 %> Use subclasses to create a GAMS Symbol, see subclass help.

diff --git a/+gams/+transfer/SymbolType.m b/+gams/+transfer/SymbolType.m
@@ -35,7 +35,6 @@
 % compatibility (e.g. for Octave).
 %
 
-%> @ingroup symbol
 %> @brief GAMS Transfer Symbol Types
 %>
 %> This class holds the possible GAMS Transfer symbol types similar to an

diff --git a/+gams/+transfer/UniverseAlias.m b/+gams/+transfer/UniverseAlias.m
@@ -44,7 +44,6 @@
 %
 % See also: gams.transfer.Set, gams.transfer.Container, gams.transfer.Alias
 
-%> @ingroup symbol
 %> @brief GAMS Alias to Universe
 %>
 %> This class represents a GAMS Alias to Universe.

diff --git a/+gams/+transfer/Variable.m b/+gams/+transfer/Variable.m
@@ -66,7 +66,6 @@
 % See also: gams.transfer.Container, gams.transfer.VariableType, gams.transfer.Set
 %
 
-%> @ingroup symbol
 %> @brief GAMS Variable
 %>
 %> **Example:**

diff --git a/+gams/+transfer/VariableType.m b/+gams/+transfer/VariableType.m
@@ -37,7 +37,6 @@
 % See also: gams.transfer.Variable
 %
 
-%> @ingroup symbol
 %> @brief GAMS Variable Types
 %>
 %> This class holds the possible GAMS variable types similar to an enumeration

diff --git a/doc/DoxygenLayout.xml b/doc/DoxygenLayout.xml
@@ -2,7 +2,7 @@
   <!-- Generated by doxygen 1.8.17 -->
   <!-- Navigation index tabs for HTML output -->
   <navindex>
-    <tab type="mainpage" visible="yes" title=""/>
+    <tab type="mainpage" visible="no" title=""/>
     <tab type="pages" visible="yes" title="" intro=""/>
     <tab type="modules" visible="yes" title="Manual" intro=
     "GAMS Transfer Matlab consists of containers, symbols and symbol records.
@@ -18,12 +18,12 @@
       <tab type="interfaceindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="interfacehierarchy" visible="yes" title="" intro=""/>
     </tab>
-    <!-- <tab type="classes" visible="yes" title="">
+    <tab type="classes" visible="yes" title="">
       <tab type="classlist" visible="yes" title="" intro=""/>
       <tab type="classindex" visible="$ALPHABETICAL_INDEX" title=""/>
       <tab type="hierarchy" visible="yes" title="" intro=""/>
       <tab type="classmembers" visible="yes" title="" intro=""/>
-    </tab> -->
+    </tab>
     <tab type="structs" visible="yes" title="">
       <tab type="structlist" visible="yes" title="" intro=""/>
       <tab type="structindex" visible="$ALPHABETICAL_INDEX" title=""/>

diff --git a/doc/container.dox b/doc/container.dox
@@ -1,10 +1,9 @@
-/**
+/** \page GAMS_TRANSFER_MATLAB_CONTAINER Container
 
-@defgroup gams_transfer_matlab_container Container
-@brief Wrapper of symbols (like GDX file)
+\tableofcontents
 
 A GAMS Transfer Matlab container stores a collection of \ref
-gams_transfer_matlab_symbol "symbols" and is therefore comparable to a GDX file.
+GAMS_TRANSFER_MATLAB_SYMBOLS "symbols" and is therefore comparable to a GDX file.
 It is indeed a fundamental feature of containers to read from or write to GDX
 files. GDX files can be operated in two different modes, `default` and
 `indexed`, which are also supported by GAMS Transfer Matlab containers, see \ref
@@ -84,7 +83,7 @@ Finally note that GDX files store multiple values per symbol. \ref
 gams::transfer::Set "Sets" have `element_text`, \ref gams::transfer::Parameter "Parameters"
 have `value` and \ref gams::transfer::Equation "Equations" and \ref
 gams::transfer::Variable "Variables" have `level`, `marginal`, `lower`, `upper`,
-`scale`, see \ref gams_transfer_matlab_records for more information. On
+`scale`, see \ref GAMS_TRANSFER_MATLAB_RECORDS for more information. On
 default, all values are read, but you can select a subset by
 ```
 c.read(source, 'values', {'level', 'marginal'});

diff --git a/doc/getting_started.dox b/doc/getting_started.dox
@@ -1,18 +1,18 @@
 /** \page GAMS_TRANSFER_MATLAB_GETSTARTED Getting Started
 
+\tableofcontents
+
 \section GAMS_TRANSFER_MATLAB_GETSTARTED_INSTALL Install
 
 GAMS comes with a ready-to-use GAMS Transfer Matlab (for Matlab 2018a or newer).
 Simply add the GAMS Matlab API to the Matlab path:
 ```
-addpath("[PathToGAMS]/apifiles/Matlab/api")
+addpath("[PathToGAMS]/api/matlab")
 ```
 
-Note that GAMS Transfer Matlab comes as a Matlab package and, thus, all classes
-must be prefixed with `gams.transfer.`. In order to avoid this, you can import
-the package with:
+For other software products, e.g. Octave, you must compile the MEX source code first. Simply run:
 ```
-import gams.transfer.*
+gams.transfer.setup()
 ```
 
 \section GAMS_TRANSFER_MATLAB_GETSTARTED_EXAMPLE Example

diff --git a/doc/main.dox b/doc/main.dox
@@ -1,65 +1,26 @@
 /** \mainpage GAMS Transfer Matlab
 
-\section GAMS_TRANSFER_MATLAB_INTRO Introduction
-
-GAMS Transfer is a package to maintain GAMS data outside a GAMS script in a
-programming language like Python or Matlab. It allows the user to add GAMS
-symbols (Sets, Parameters, Variables and Equations), to manipulate GAMS symbols,
-read symbols from a GDX file or write them to one. While keeping those
-operations as simple as possible for the user, GAMS Transfer's main focus is the
-highly efficient transfer of data between GAMS and the target programming
-language. In order to achieve this, symbol records – the actual and potentially
-large-scale data sets – are stored in native data structures of the
-corresponding programming languages, e.g., dataframes, tables or (sparse)
-matrices. The benefits of this approach are threefold:
+GAMS Transfer is a package to maintain GAMS data outside a GAMS script. It allows the user to add
+GAMS symbols (Sets, Parameters, Variables and Equations), to manipulate GAMS symbols, read symbols
+from a GDX file or write them to one. While keeping those operations as simple as possible for the
+user, GAMS Transfer Matlab's main focus is the highly efficient transfer of data between GAMS and
+Matlab. In order to achieve this, symbol records (the actual and potentially large-scale data sets)
+are stored in native data structures of Matlab (tables, structs or (sparse) matrices). The benefits
+of this approach are threefold:
 - The user is usually very familiar with these data structures.
 - These data structures come with a large tool box for various data operations.
-- Optimized methods for reading from and writing to GDX can transfer the data as
-  a bulk –- resulting in the high performance of this package.
-
-\image html overview.jpg
-\image latex overview.jpg
-
-\subsection GAMS_TRANSFER_MATLAB_VS Using GAMS Transfer Matlab or ...?
-
-\subsubsection GAMS_TRANSFER_MATLAB_VS_API ...GAMS Matlab API?
-
-[GAMS Matlab API]: https://www.gams.com/latest/docs/API_MATLAB_GAMS_OVERVIEW.html
-
-Both, the [GAMS Matlab API] and GAMS Transfer Matlab allow to exchange data from
-Matlab with GAMS. However, GAMS Transfer Matlab focuses on data exchange and for
-this is much more efficient. Moreover, it offers a richer set of features to
-read and write GDX files. On the contrary, the [GAMS Matlab API] can manage GAMS
-jobs which GAMS Transfer Matlab cannot do. In summary, if you are only using the
-[GAMS Matlab API] for data exchange, consider using GAMS Transfer Matlab
-instead.
-
-\subsubsection GAMS_TRANSFER_MATLAB_VS_GDXMRW ...GDXMRW?
-
-[GDXMRW]: https://www.gams.com/latest/docs/T_GDXMRW.html
-
-[GDXMRW] has been [deprecated since GAMS
-38](https://www.gams.com/latest/docs/RN_38.html#g3810_GDXMRW) and may be removed
-in a future GAMS release. Please migrate to GAMS Transfer Matlab instead. While
-the purpose of these two is similar, GAMS Transfer Matlab offers more features,
-a more user-friendly interface and is actively maintained.
-
-\subsection GAMS_TRANSFER_MATLAB_USE_DOC Using the GAMS Transfer Matlab Documentation
-
-If you are new to GAMS Transfer Matlab, have a look at \ref
-GAMS_TRANSFER_MATLAB_GETSTARTED. This section explains how to install GAMS
-Transfer Matlab and shows a first exmaple that covers the most important
-operations. It's a good starting point to discover GAMS Transfer Matlab. For
-more details, refer to the manual for: (1) \ref gams_transfer_matlab_container,
-(2) \ref gams_transfer_matlab_symbol and (3) \ref gams_transfer_matlab_records.
-Good advice: Read the documentation in this order as it will guide you from more
-general topics like \ref gams::transfer::Container "Container" to more detailed
-topics like \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT. Note that at the bottom of
-each of the three, you can find a list of GAMS Transfer Matlab classes that
-belong to the corresponding topic. Those class documentations document each
-method and property of the classes and give a good overview of what the class is
-capable of. Finally, once installed, it is also possible to get help from within
-Matlab. Simply run:
+- Optimized methods for reading from and writing to GDX can transfer the data as a bulk –- resulting
+  in the high performance of this package.
+
+If you are new to GAMS Transfer Matlab, have a look at \ref GAMS_TRANSFER_MATLAB_GETSTARTED. It
+explains how to install GAMS Transfer Matlab and shows a first exmaple that covers the most
+important operations. It's a good starting point to discover GAMS Transfer Matlab. For more details,
+refer to the manual for: (1) \ref GAMS_TRANSFER_MATLAB_CONTAINER, (2) \ref
+GAMS_TRANSFER_MATLAB_SYMBOLS and (3) \ref GAMS_TRANSFER_MATLAB_RECORDS. Good advice: Read the
+documentation in this order as it will guide you from more general topics like \ref
+gams::transfer::Container "Container" to more detailed topics like \ref
+GAMS_TRANSFER_MATLAB_RECORDS_FORMAT. Furthermore, it is also possible to get help from within
+Matlab:
 ```
 help GAMSTransfer
 ```

diff --git a/doc/records.dox b/doc/records.dox
@@ -1,23 +1,22 @@
-/**
+/** \page GAMS_TRANSFER_MATLAB_RECORDS Records
 
-@defgroup gams_transfer_matlab_records Records
-@brief Symbol Records
+\tableofcontents
 
 Symbol records are the actual data. In GAMS Transfer Matlab they are stored in
 Matlab native data structures, structs, tables, dense or sparse matrices (see
 \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT for more information). In GDX, a record
 is the combination of domain entry data and value data. Domain entries are given
 as \ref GAMS_TRANSFER_MATLAB_RECORDS_UELS "UELs" using Matlab `categorical`. Work
 with `categorical` as you would work with strings -- it's just a way to save
-memory. The values a \ref gams_transfer_matlab_symbol "symbol" stores per record
+memory. The values a \ref GAMS_TRANSFER_MATLAB_SYMBOLS "symbol" stores per record
 depends on the \ref gams::transfer::SymbolType "symbol type". \ref
 gams::transfer::Set "Sets" have `element_text`, \ref gams::transfer::Parameter "Parameters"
 have `value` and \ref gams::transfer::Equation "Equations" and \ref
 gams::transfer::Variable "Variables" have `level`, `marginal`, `lower`, `upper` and
 `scale`. If some of these value fields are not provided, then default values are
 used. A \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "record format" is chosen for
 each symbol and not for each of these values independently. Hence note, a \ref
-gams_transfer_matlab_container "container" can store different symbols with
+GAMS_TRANSFER_MATLAB_CONTAINER "container" can store different symbols with
 different \ref GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "record formats".
 
 When working with symbol records, there are two things that can go wrong:

diff --git a/doc/symbols.dox b/doc/symbols.dox
@@ -1,13 +1,12 @@
-/**
+/** \page GAMS_TRANSFER_MATLAB_SYMBOLS Symbols
 
-@defgroup gams_transfer_matlab_symbol Symbols
-@brief Symbols (Set, Alias, Parameter, Variable, Equation)
+\tableofcontents
 
 A symbol is either a GAMS \ref gams::transfer::Set "Set", \ref gams::transfer::Alias
 "Alias", \ref gams::transfer::Parameter "Parameter", \ref gams::transfer::Variable
 "Variable" or \ref gams::transfer::Equation "Equation". In GAMS Transfer Matlab, a
 symbol cannot live on it's own, but is always part of a \ref
-gams_transfer_matlab_container "container".
+GAMS_TRANSFER_MATLAB_CONTAINER "container".
 
 \section GAMS_TRANSFER_MATLAB_SYMBOL_DOMAIN Symbol Domain
 
@@ -124,7 +123,7 @@ apply, see also \ref GAMS_TRANSFER_MATLAB_RECORDS_DOMVIOL.
 Need more convenience by sacrificing efficiency? Go to \ref
 GAMS_TRANSFER_MATLAB_SYMBOL_CONVENIENT_RECORDS.
 
-Symbol \ref gams_transfer_matlab_records "records" are stored in the property
+Symbol \ref GAMS_TRANSFER_MATLAB_RECORDS "records" are stored in the property
 \ref gams::transfer::Symbol::records "Symbol.records". It is most efficient to
 modify the data inplace. Note that the records have to satisfy the chosen \ref
 GAMS_TRANSFER_MATLAB_RECORDS_FORMAT "records format". Otherwise, the symbol will

diff --git a/gams_transfer_doc.sh b/gams_transfer_doc.sh
@@ -3,7 +3,7 @@
 mkdir -p build
 
 (cat doc/Doxyfile && \
-    echo "PROJECT_NUMBER=0.7.0"; \
+    echo "PROJECT_NUMBER=0.8.0"; \
     echo "INPUT=+gams doc/main.dox doc/getting_started.dox doc/container.dox doc/symbols.dox doc/records.dox"; \
     echo "OUTPUT_DIRECTORY=build/doc"; \
     echo "FILTER_PATTERNS=*m=ext/doxymatlab/m2cpp.pl"; \