Updating documentation (#1212)

* Fixing some warning for sphinx build of user's guide * Adding README to User's Guide * Exclude rst files from api
OpenModelica · Apr 27, 2023 · eaf993a · eaf993a
1 parent 2cd3a45
commit eaf993a
Show file tree

Hide file tree

Showing 11 changed files with 51 additions and 20 deletions.
diff --git a/doc/UsersGuide/Makefile b/doc/UsersGuide/Makefile
@@ -1,7 +1,7 @@
 # Makefile for Sphinx documentation
 #
 
-OMSIMULATOR_ROOT = $(CURDIR)/../../
+OMSIMULATOR_ROOT = $(CURDIR)/../..
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
@@ -23,6 +23,8 @@ else
 	INSTALL_DIR := install/linux
 endif
 
+OMSIMULATORHOME := $(OMSIMULATOR_ROOT)/$(INSTALL_DIR)/bin
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
@@ -190,6 +192,6 @@ pseudoxml:
 all-dep: source/omsimulator-help.inc
 
 source/omsimulator-help.inc:
-	$(OMSIMULATOR_ROOT)/$(INSTALL_DIR)/bin/OMSimulator --help > "$@.tmp"
+	$(OMSIMULATORHOME)/OMSimulator --help > "$@.tmp"
 	mv "$@.tmp" "$@"
 	cp "$@" source/api/
diff --git a/doc/UsersGuide/README.md b/doc/UsersGuide/README.md
@@ -0,0 +1,21 @@
+# User's Guide
+
+OMSimulator User's Guide using Sphinx (Python Documentation Generator).
+
+## Dependencies
+
+ - OMSimulator
+ - [Sphinx](http://sphinx-doc.org/)
+ - Python3
+
+## Build instructions
+
+```bash
+make html
+```
+
+## Preview build
+
+```bash
+python3 -m http.server --directory build/html
+```
diff --git a/doc/UsersGuide/source/OMEdit.rst b/doc/UsersGuide/source/OMEdit.rst
@@ -17,7 +17,7 @@ See also `FMI documentation <https://openmodelica.org/doc/OpenModelicaUsersGuide
 and `SSP documentation <https://ssp-standard.org/>`_.
 
 .. figure :: images/omedit_01.png
-  :name: omedit-mainwindow-browsers
+  :name: oms-omedit-mainwindow-browsers
 
   OMEdit MainWindow and Browsers.
 

diff --git a/doc/UsersGuide/source/OMSimulatorLib.rst b/doc/UsersGuide/source/OMSimulatorLib.rst
@@ -1,14 +1,14 @@
 .. index:: OMSimulatorLib
 
 OMSimulatorLib
-=================
+==============
 
 This library is the core of OMSimulator and provides a C interface that can
 easily be utilized to handle co-simulation scenarios.
 
 .. index:: OMSimulatorLib; C-API
 
 C-API
-#####
+=====
 
 .. include:: OMSimulatorLib.inc
diff --git a/doc/UsersGuide/source/OMSimulatorLua.rst b/doc/UsersGuide/source/OMSimulatorLua.rst
@@ -11,7 +11,7 @@ library.
 .. index:: OMSimulatorLua; Examples
 
 Examples
-########
+--------
 
 .. code-block:: lua
 

diff --git a/doc/UsersGuide/source/OMSimulatorPython.rst b/doc/UsersGuide/source/OMSimulatorPython.rst
@@ -17,7 +17,7 @@ Installation using ``pip`` is recommended:
 .. index:: OMSimulatorPython; Examples
 
 Examples
-########
+--------
 
 .. code-block:: python
 
@@ -85,12 +85,12 @@ following example is equivalent to the previous one:
 .. index:: OMSimulatorPython; Scripting Commands
 
 Python Scripting Commands
-#########################
+-------------------------
 
 .. include:: OMSimulatorPython.inc
 
 Example: Pi
-###########
+^^^^^^^^^^^
 
 This example uses a simple Modelica model and FMI-based batch
 simulation to approximate the value of pi.

diff --git a/doc/UsersGuide/source/OpenModelicaScripting.rst b/doc/UsersGuide/source/OpenModelicaScripting.rst
@@ -9,7 +9,7 @@ OMSimulatorLib library.
 .. index:: OpenModelicaScripting; Examples
 
 Examples
-########
+--------
 
 .. code-block:: modelica
 
@@ -43,6 +43,6 @@ Examples
 .. index:: OpenModelicaScripting; Scripting Commands
 
 OpenModelica Scripting Commands
-###############################
+-------------------------------
 
 .. include:: OMCScripting.inc
diff --git a/doc/UsersGuide/source/SSP.rst b/doc/UsersGuide/source/SSP.rst
@@ -9,7 +9,7 @@ Composite models are imported and exported in the *System Structure Description
 .. index:: SSP; Bus connections
 
 Bus Connections
-###############
+---------------
 
 Bus connections are saved as annotations to the SSD file. Bus connectors are only allowed in weakly coupled and strongly coupled systems. Bus connections can exist in any system type. Bus connectors are used to hide SSD connectors and bus connections are used to hide existing SSD connections in the graphical user interface. It is not required that all connectors referenced in a bus are connected. One bus may be connected to multiple other buses, and also to SSD connectors.
 
@@ -80,7 +80,7 @@ The example below contains a root system with two subsystems, ``WC1`` and ``WC2`
 .. index:: SSP; TLM Systems
 
 TLM Systems
-###########
+-----------
 
 TLM systems are only allowed on top-level. SSD annotations are used to specify the system type inside the ``ssd:SimulationInformation`` tag, as shown in the example below. Attributes ``ip``, ``managerport`` and ``monitorport`` defines the socket communication, used both to exchange data with external tools and with internal simulation threads.
 
@@ -109,7 +109,7 @@ TLM systems are only allowed on top-level. SSD annotations are used to specify t
 .. index:: SSP; TLM connections
 
 TLM Connections
-###############
+---------------
 
 TLM connections are implemented without regular SSD connections. TLM connections are only allowed in TLM systems. TLM connectors are only allowed in weakly coupled or strongly coupled systems. Both connectors and connections are implemented as SSD annotations in the System tag.
 

diff --git a/doc/UsersGuide/source/api/duplicateVariant.rst b/doc/UsersGuide/source/api/duplicateVariant.rst
@@ -32,9 +32,10 @@ as default variant.
 
 #END#
 
-
 #DESCRIPTION#
-  An example of creating a multi-variant modelling is presente below
+An example of creating a multi-variant modelling is presented below
+
+.. code-block:: lua
 
   oms_newModel("model")
   oms_addSystem("model.root", "system_wc")
@@ -45,7 +46,9 @@ as default variant.
   oms_setReal("varB.root.A.param2", "20")
   oms_export("varB", "variant.ssp")
 
-  The variant.ssp file will have the following structure
+The variant.ssp file will have the following structure
+
+.. code-block::
 
   Variant.ssp
       SystemStructure.ssd

diff --git a/doc/UsersGuide/source/api/listVariants.rst b/doc/UsersGuide/source/api/listVariants.rst
@@ -29,7 +29,9 @@ This API shows the number of variants available [(e.g). SystemStructure.ssd, Var
 
 
 #DESCRIPTION#
-  An example for finding the number of available variants in a ssp file
+An example for finding the number of available variants in a ssp file
+
+.. code-block:: lua
 
   oms_newModel("model")
   oms_addSystem("model.root", "system_wc")
@@ -39,7 +41,10 @@ This API shows the number of variants available [(e.g). SystemStructure.ssd, Var
 
   oms_listVariants("varB")
 
-  The API will list the available variants like below
+The API will list the available variants like below
+
+.. code-block::
+
   <oms:Variants>
     <oms:variant name="model" />
     <oms:variant name="varB" />

diff --git a/doc/UsersGuide/source/conf.py b/doc/UsersGuide/source/conf.py
@@ -77,7 +77,7 @@
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ["api"]
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.