doc: Switching documentation to Sphinx (#6)

Author: gliga

.github/workflows/documentation.yml

@@ -0,0 +1,25 @@
+name: documentation
+run-name: ${{ github.ref_name }} documentation
+on: [push, pull_request]
+permissions:
+  contents: write
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-python@v3
+      - name: Install dependencies
+        run: |
+          pip install sphinx sphinx_rtd_theme myst_parser
+      - name: Sphinx build
+        run: |
+          sphinx-build doc _build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        with:
+          publish_branch: gh-pages
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: _build/
+          force_orphan: true

.gitignore

@@ -1,3 +1,4 @@
 
 *~
 .objects/
+doc/_build

README.md

@@ -6,11 +6,11 @@
 [![test (mac)](https://github.com/EngineeringSoftware/gobash/actions/workflows/test-mac.yml/badge.svg)](https://github.com/EngineeringSoftware/gobash/actions/workflows/test-mac.yml)
 [![lint](https://github.com/EngineeringSoftware/gobash/actions/workflows/lint.yml/badge.svg)](https://github.com/EngineeringSoftware/gobash/actions/workflows/lint.yml)
 
-`gobash` library is a set of functions that improve programming
-experience in `bash` (by providing collections, languages features,
-APIs, testing package, command line flag parsing, etc.)  without
-modifying the shell interpreter(s).  It works with any bash version
-(on Linux and Mac).  Parts of the API are matching those in Go.
+`gobash` is a set of functions that improve programming experience in
+`bash` (by providing collections, languages features, APIs, testing
+package, command line flag parsing, etc.)  without modifying the shell
+interpreter(s).  It works with any bash version (on Linux and Mac).
+Parts of the API are matching those in Go.
 
 If you cannot wait to see code, here is a quick example (but check
 later sections for a lot more):
@@ -411,7 +411,6 @@ make_and_print
 # }
 ```
 
-
 ### Methods
 
 Adding a method to a struct is done by implementing a function that is
@@ -753,9 +752,9 @@ $ $p to_string
 # }
 ```
 
-One of the (obvious) implications is that you can now write scripts
-that accept objects, and those scripts can be invoked from your
-terminal with objects made in the terminal process.
+One of the implications is that you can now write scripts that accept
+objects, and those scripts can be invoked from your terminal with
+objects made in the terminal process.
 
 Consider the script below (`ai`). (This is the same example we used
 in an earlier section to illustrate inter-process communication.)
@@ -980,9 +979,9 @@ improving the performance, but we might wait for a couple of users.
 
 ## Dependencies
 
-`gobash` uses several binaries widely avaialble on Unix. Although
-things keep changing, the list likely includes `jq`, `sed`, `grep`,
-`awk`, `date`.
+`gobash` uses several bash builtins, GNU coreutils, and binaries
+widely avaialble on Unix. Although the repository keep changing, the
+list probably includes `jq`, `sed`, `grep`, `awk`, `date`.
 
 
 ## Versioning

doc/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     = .
+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)

doc/collections.rst

@@ -0,0 +1,40 @@
+
+Collections
+===========
+
+gobash introduces two key collections: `List` and `Map`. Both
+collections include a number of methods that can be convenient for
+everyday development.
+
+In the example below, we use an instance of a `List` to keep URLs of
+several GitHub projects and then close each of those projects in a
+loop.
+
+.. code-block:: bash
+
+   #!/bin/bash
+   . gobash/gobash
+
+   lst=$(List)
+   $lst add "https://github.com/apache/commons-math"
+   $lst add "https://github.com/apache/commons-io"
+
+   # Print length.
+   $lst len
+
+   # Clone each repo.
+   for (( i=0; i<$($lst len); i++)); do
+           git clone $($lst get $i)
+   done
+
+   # Print the list.
+   $lst to_string
+
+.. note::
+
+   Equality in `gobash` is done based on object identity. Future
+   changes could consider using `eq` methods to check for equality
+   (similar to other programming languages).
+
+.. toctree::
+   :maxdepth: 2

doc/command-line-flags.rst

@@ -0,0 +1,42 @@
+
+Command Line Flags
+==================
+
+gobash can simplify parsing command line flags. In the next example,
+we illustrate parsing using the `flags` package. Specifically, we
+create `Flags` with desired documentation and add two flags. Each flag
+has to include name, type (int, bool, float, or string), and
+documentation.
+
+.. code-block:: bash
+
+    #!/bin/bash
+    . gobash/gobash
+    
+    min=$(Flag "x" "int" "Min value.")
+    max=$(Flag "y" "int" "Max value.")
+    
+    flags=$(Flags "Flags to demo flag parsing.")
+    $flags add "$min"
+    $flags add "$max"
+
+Once we build the flags, we can print a help message simply like this:
+
+.. code-block:: bash
+
+    $flags help
+
+Parsing flags is then done in a few steps:
+
+.. code-block:: bash
+
+    args=$(Args) # an object that will keep parsed values
+    ctx=$(ctx_make) # context will store an issue is encountered during parsing
+    $flags $ctx parse "$args" "$@" || \
+        { ctx_show $ctx; exit 1; } # checking for errors
+    
+    $args x # print the parsed x value
+    $args y # print the parsed y value
+
+.. toctree::
+   :maxdepth: 2

doc/conf.py

@@ -0,0 +1,27 @@
+# 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 = 'gobash'
+copyright = '2024, Milos Gligoric'
+author = 'Milos Gligoric'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+html_theme = 'alabaster'
+html_static_path = ['_static']

doc/design.rst

@@ -0,0 +1,14 @@
+
+Design
+======
+
+Key design goal: Implement everything using functions and files (i.e.,
+there is no need to change existing shells or existing user code).
+
+As the result, a user can adopt gobash as needed without being forced
+to rewrite any of their code, but can benefit by using some/all of
+gobash features, which can be introduced gradually.  Additionally,
+gobash should work with any `bash` version and OS that runs `bash`.
+
+.. toctree::
+   :maxdepth: 2

doc/get-started.rst

@@ -0,0 +1,158 @@
+
+Get Started
+===========
+
+It is trivial to get started using gobash, because it only adds to the
+knowledge you already have about shell programming. Also, it does not
+require any special setup, because everything is pure bash.
+
+There are two modes in which gobash can be used: (a) as a library,
+or (b) as a tool. Most of the examples below use gobash as a library
+(i.e., source gobash into a script and use available functions). There
+is a separate section to describe using gobash as a tool.
+
+We will use several examples in this section to get you started.
+
+Prepare Environment
+-------------------
+
+Create a space for trying gobash:
+
+.. code-block:: bash
+
+    mkdir space
+    cd space
+
+Clone the gobash repository:
+
+.. code-block:: bash
+
+    git clone [email protected]:EngineeringSoftware/gobash
+
+Alternatively, you can avoid cloning the repo and directly source the
+library in your bash script:
+
+.. code-block:: bash
+
+    source /dev/stdin <<< "$(curl https://raw.githubusercontent.com/EngineeringSoftware/gobash/master/hsabog 2>/dev/null)"
+
+Now, we are ready to run some examples.
+
+Collection Example
+------------------
+
+Write your first script (let's call it `s`) that uses gobash. The
+example below "imports" the entire gobash library and uses the `List`
+collection for storing values.
+
+.. code-block:: bash
+
+    #!/bin/bash
+    . gobash/gobash
+    
+    # Instantiate a list and add two elements.
+    lst=$(List)
+    $lst add 55
+    $lst add 100
+    
+    # Get the length of the list.
+    $lst len
+    # Output: 2
+    
+    # Print the list (default print is in the json format).
+    $lst to_string
+    # Output:
+    # [
+    #   "55",
+    #   "100"
+    # ]
+
+Struct Example
+--------------
+
+In the following example (`point.sh`), we introduce a `struct` for a
+2D point, set/get values, and write a function to add two points.
+
+.. code-block:: bash
+
+    #!/bin/bash
+    . gobash/gobash
+    
+    function Point() {
+            make_ $FUNCNAME \
+                  "x" "$1" \
+                  "y" "$2"
+    }
+    
+    function point_add() {
+            local p1="${1}"
+            local p2="${2}"
+    
+            local x=$(( $($p1 x) + $($p2 x) ))
+            local y=$(( $($p1 y) + $($p2 y) ))
+            local p3=$(Point "${x}" "${y}")
+            echo "$p3"
+    }
+    
+    p1=$(Point 3 4)
+    p2=$(Point 8 9)
+    p3=$(point_add "$p1" "$p2")
+    $p3 to_string
+    # Output:
+    # {
+    #   "x": "11",
+    #   "y": "13"
+    # }
+
+Test Example
+------------
+
+This example illustrate a way to write tests using a testing package.
+The tests can be executed with the gobash tool.
+
+We will extend the previous example to add tests (`point_test.sh`) for
+the function `point_add`.
+
+.. code-block:: bash
+
+    #!/bin/bash
+    
+    . point.sh
+    
+    function test_point() {
+            p1=$(Point 3 4)
+            p2=$(Point 8 9)
+            p3=$(point_add "$p1" "$p2")
+            assert_ze $?
+            assert_eq 11 $($p3 x)
+            assert_eq 13 $($p3 y)
+    }
+
+Tests can be run with the following command:
+
+.. code-block:: bash
+
+    ./gobash test --paths point_test.sh --verbose
+
+The output of this execution will be along these lines:
+
+.. code-block:: bash
+
+        test_point start
+        test_point PASSED
+      ./point_test.sh 1[sec]
+    Tests run: 1, failed: 0, skipped: 0.
+    Total time: 1[sec]
+
+Further Reading
+---------------
+
+There are a number of other examples that illustrate gobash in the
+`examples directory
+<https://github.com/EngineeringSoftware/gobash/tree/main/examples/README.md>`_.
+If you like learning by examples, that is the best place to go next.
+If you prefer to read higher level doc, then check
+:doc:`language`.
+
+.. toctree::
+   :maxdepth: 2