Merge pull request #2 from julianmendez/18-improved-documentation

18 improved documentation

.github/workflows/ci.yml

@@ -20,7 +20,7 @@ jobs:
         - 2.11.12
         - 2.12.17
         - 2.13.10
-        - 3.2.2
+        - 3.3.0
     steps:
     - name: Check out
       uses: actions/checkout@v3

.gitignore

@@ -12,3 +12,4 @@ Thumbs.db
 .cache
 .cache-main
 .cache-tests
+docs/sphinx/build

.readthedocs.yaml

@@ -0,0 +1,22 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+sphinx:
+   configuration: docs/sphinx/source/conf.py
+
+# formats:
+#    - pdf
+
+python:
+   install:
+   - requirements: docs/sphinx/requirements.txt
+
+

build.sbt

@@ -6,14 +6,14 @@ lazy val scala2_12 = "2.12.17"
 
 lazy val scala2_13 = "2.13.10"
 
-lazy val scala3_2 = "3.2.2"
+lazy val scala3_3 = "3.3.0"
 
 lazy val commonSettings =
   Seq(
     organization := "se.umu.cs.rai.soda",
-    version := "0.17.0",
-    description := "Functional language to describe ethical problems",
-    homepage := Some(url("https://bitbucket.org/mendezjulian/soda")),
+    version := "0.18.0",
+    description := "Object-oriented functional language to describe, analyze, and model human-centered problems",
+    homepage := Some(url("https://julianmendez.github.io/soda/")),
     startYear := Some(2020),
     licenses := Seq("Apache License Version 2.0" -> url("https://www.apache.org/licenses/LICENSE-2.0.txt")),
     organizationName := "Responsible Artificial Intelligence - Umea University",
@@ -28,15 +28,15 @@ lazy val commonSettings =
      * [[https://repo1.maven.org/maven2/org/scala-lang/scalap/]]
      * [[https://repo1.maven.org/maven2/org/scala-lang/scala3-compiler_3/]]
      */
-    crossScalaVersions := Seq(scala2_11, scala2_12, scala2_13, scala3_2),
-    scalaVersion := scala3_2,
+    crossScalaVersions := Seq(scala2_11, scala2_12, scala2_13, scala3_3),
+    scalaVersion := scala3_3,
     /**
      * ScalaTest
      * [[https://www.scalatest.org]]
      * [[https://github.com/scalatest/scalatest]]
      * [[https://repo1.maven.org/maven2/org/scalatest/]]
      */
-    libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.15" % "test",
+    libraryDependencies += "org.scalatest" %% "scalatest" % "3.2.16" % "test",
     resolvers += Resolver.mavenLocal,
     publishTo := Some(Resolver.mavenLocal),
     publishMavenStyle := true,

docs/README.md

@@ -1,10 +1,10 @@
 # Soda
 
-*Soda* (Symbolic Objective Descriptive Analysis) is a functional language to describe ethical problems. Its main purpose
-is to be used to produce clear code. The source code should be easy to understand, somehow natural, although not
-necessarily easy to write.
+*Soda* (Symbolic Objective Descriptive Analysis) is an object-oriented functional language to describe, analyze, and
+model human-centered problems.
+Due to its readability, it can be applied to model ethical problems.
 
-This project includes a translator to Scala.
+This project includes a translator to [Scala](https://scala-lang.org).
 
 
 ## Reserved words
@@ -28,10 +28,12 @@ The reserved words are:
 ## Other Symbols
 
 In addition, the language has:
+
 - `(` and `)` (parentheses) for parameters and operator precedence
 - `[` and `]` (square brackets) for parametric types
 
 The main arithmetic operators are:
+
 - `+`, `-`, `*`, `/`, `%` (modulus)
 
 Comments are marked with `/*` and `*/`. Scaladoc / Javadoc markers are `/**` and `*/`.
@@ -51,25 +53,24 @@ Special names:
 
 ## Side Effects
 
-In this language, variables cannot change their value. Therefore, there is no equivalent to `var`.
-
-For example, it is not possible to write `x = x + 1`. Loops can be managed with `range` and `fold` functions, tail recursion, or directly using streams.
+In Soda, variables cannot change their value. Thus, it is not possible to write `x = x + 1`.
+Loops can be managed with `range` and `fold` functions and tail recursion.
 
 The language does not provide `throw`, `try`, and `catch`, because those commands do not follow the functional style.
 
 
 ## Static Typing
 
 This language is statically typed. It is possible to define abstract and concrete classes.
-
-A *class* is like a *trait* in Scala. Each class should have a single class constructor. The class constructor is
-implemented with a *concrete class*, which is like a *case class* in Scala.
+Each *class* (like a *trait* in Scala) can be extended and has a single class constructor.
+This constructor is implemented with a *concrete class* (like a *case class* in Scala).
 
 
 ## Package Declaration and Imports
 
-This language is designed to be integrated via the Java Virtual Machine. It is possible to define the package and to
-declare the imports.
+Soda is designed to be integrated via the Java Virtual Machine.
+It is possible to define packages and to declare imports.
+This can be done in a separate file `Package.soda`, which is in the same directory as the source code.
 
 
 ## Syntax Highlighting
@@ -80,14 +81,17 @@ The following tools can be configured to have syntax highlighting:
 - gedit (configuration file: soda.lang)
 
 
-## Build
+## Documentation
+
+- [User manual](https://soda-lang.readthedocs.io/en/latest/)
 
-The project can be built with [sbt](https://www.scala-sbt.org/).
 
-The command is:
+## Build
+
+The project can be built with [sbt](https://www.scala-sbt.org/) with
 `sbt clean compile test package assembly`
 
-It is also possible to compile it for different Scala versions.
+A Linux binary can be created with the script `makeall.sh`.
 
 
 ## Author

docs/RELEASE-NOTES.md

@@ -1,4 +1,16 @@
 ---
+- - version: v0.18.0
+  - date: '2023-06-01'
+  - build: sbt '++ 3.3.0' clean compile test package assembly
+  - release: target/scala-3.3.0/soda-0.18.0.jar
+  - new_features:
+    - assumes translation to `Package.scala` files as default configuration for the Scala translator
+    - expects multiple type parameters to be between different square brackets, e.g. `MyPair [A] [B]` instead of `MyPair [A, B]`
+    - accepts intersection types (built with `&`) and union types (built with `|`)
+  - bug_fixes:
+    - fixes translation of reserved words after opening parenthesis
+    - fixes edge case of directory scanner when translating multiple Soda files to Scala
+    - fixes processing of Soda files when Package.soda file is missing
 - - version: v0.17.0
   - date: '2023-03-01'
   - build: sbt '++ 3.2.2' clean compile test package assembly

docs/sphinx/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/sphinx/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/sphinx/requirements.txt

@@ -0,0 +1 @@
+sphinx_rtd_theme

docs/sphinx/source/appendix/index.rst

@@ -0,0 +1,36 @@
+********
+Appendix
+********
+
+
++------------------------------------------+---------------------------------------------------------------------+
+| *f* = *e*                                | function or constant definition of *f* as *e*                       |
++------------------------------------------+---------------------------------------------------------------------+
+| *x* : *A*                                | declaration that *x* is of type *A*                                 |
++------------------------------------------+---------------------------------------------------------------------+
+| **lambda** (*x* : *A*) -`-`> *e*         | lambda definition for λ (*x* : *A*) . *e*, where *x* is of type *A* |
++------------------------------------------+---------------------------------------------------------------------+
+| *t* := *e*                               | assignment of parameter *t* to have value *e*                       |
++------------------------------------------+---------------------------------------------------------------------+
+| **if** *b* **then** *e₁* **else** *e₂*   | expression if *b* is true, then *e₁*, else *e₂*                     |
++------------------------------------------+---------------------------------------------------------------------+
+| **match** *x* **case** *pᵢ* ==> *eᵢ*     | pattern matching from *pᵢ* to *eᵢ* for 1 ≤ *i* ≤ *n*                |
++------------------------------------------+---------------------------------------------------------------------+
+| **class** *B* **extends** *A₁* ... *Aₙ*  | class *B* extends classes *A₁* ... *Aₙ*                             |
++------------------------------------------+---------------------------------------------------------------------+
+| *A₁* **subtype** *A₂*                    | *A₁* extends *A₂*                                                   |
++------------------------------------------+---------------------------------------------------------------------+
+| *A₁* **supertype** *A₂*                  | *A₁* is extended by *A₂*                                            |
++------------------------------------------+---------------------------------------------------------------------+
+| **abstract** *f₁* ... *fₙ*               | block of functions or constants *fᵢ* to be defined                  |
++------------------------------------------+---------------------------------------------------------------------+
+| **this**                                 | reference to itself as an instance                                  |
++------------------------------------------+---------------------------------------------------------------------+
+| **end**                                  | end of class definition                                             |
++------------------------------------------+---------------------------------------------------------------------+
+| **package**                              | package declaration for this piece of code                          |
++------------------------------------------+---------------------------------------------------------------------+
+| **import** *p*                           | block of import declarations                                        |
++------------------------------------------+---------------------------------------------------------------------+
+
+

docs/sphinx/source/conf.py

@@ -0,0 +1,52 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Soda'
+copyright = '2020--2023, Julian Alfredo Mendez'
+author = 'Julian Alfredo Mendez'
+release = '0.18.0'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# The language for content autogenerated by Sphinx. Refer to documentation
+# for a list of supported languages.
+#
+# This is also used if you do content translation via gettext catalogs.
+# Usually you set "language" from the command line for these cases.
+language = 'en'
+
+# The name of the Pygments (syntax highlighting) style to use.
+# For now, this is the most similar lexer.
+# https://github.com/pygments/pygments/blob/master/pygments/lexers/jvm.py
+
+pygments_style = 'sphinx'
+highlight_language = 'Scala'
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'sphinx_rtd_theme'
+html_static_path = ['_static']
+
+# -- Options for LaTeX output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-latex-output
+
+latex_additional_files = ["unicode-symbols.tex"]
+
+latex_elements = { 'preamble': r'''
+\input{unicode-symbols.tex}
+'''}
+
+

docs/sphinx/source/discussion/index.rst

@@ -0,0 +1,10 @@
+************
+Introduction
+************
+
+
+**Soda** (Symbolic Objective Descriptive Analysis) is a human-centered specification language to describe, formalize, and prototype abstract ideas.
+It has been originally designed to formalize ethical constraints.
+It allows to model entities as in object-oriented programming languages, and to model functions as in functional programming languages.
+Its main purpose is to be very clear and to express what it is intended to express.
+

docs/sphinx/source/index.rst

@@ -0,0 +1,25 @@
+.. Soda documentation master file.
+
+Documentation for the Soda language
+===================================
+
+.. note::
+
+   These documentation pages are under construction.
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   discussion/index
+   manual/index
+   appendix/index
+
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`
+