Added docs.

.gitignore

@@ -1,3 +1,4 @@
 /docs/build/
 /env/
 /.qlot
+/README

README.md

@@ -1,3 +1,155 @@
-# Setup-lisp - an Github Action to setup Common Lisp, Roswell and Qlot
+<a id='x-28DOCS-3A-40INDEX-20MGL-PAX-MINIMAL-3ASECTION-29'></a>
 
-TODO: Documentation will be written soon!
+# GitHub Action to setup Common Lisp for CI
+
+## Table of Contents
+
+- [1 What this action does for you?][f73c]
+- [2 A typical usage][ff56]
+- [3 Overriding qlfile][d1d0]
+
+###### \[in package DOCS with nicknames DOCS/DOCS\]
+This is a Github Action to setup Common Lisp, Roswell and Qlot.
+
+It is useful to call it before running tests or building docs
+for your Common Lisp libraries. Action encapsulates all steps
+necessary to make available [Roswell](https://github.com/roswell/roswell)
+and [Qlot](https://github.com/fukamachi/qlot) inside the Github CI.
+
+<a id='x-28DOCS-3A-40FEATURES-20MGL-PAX-MINIMAL-3ASECTION-29'></a>
+
+## 1 What this action does for you?
+
+- It installs Roswell and all it's dependencies, doing right thing depending on
+  the operating system. It should work on Ubuntu, OSX and maybe Windows.
+
+- Upgrade `ASDF` to the latest version.
+
+- Installs Qlot.
+
+- Adds to `PATH` these directories: `~/.roswell/bin` and `.qlot/bin`
+
+- Creates `.qlot` by running `qlot install`. How to override content of the
+  `qlfile`, see "Overriding qlfile" section.
+
+- And finally, it can install a specified `ASDF` system and all it's dependencies.
+  But this step is optional.
+
+
+<a id='x-28DOCS-3A-40TYPICAL-USAGE-20MGL-PAX-MINIMAL-3ASECTION-29'></a>
+
+## 2 A typical usage
+
+Here is how a minimal GitHub Workflow might look like:
+
+```yaml
+name: 'CI'
+
+on:
+  push:
+    branches:
+      - 'main'
+      - 'master'
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        lisp:
+          - sbcl-bin
+          - ccl-bin
+          
+    env:
+      LISP: ${{ matrix.lisp }}
+
+    steps:
+      - uses: actions/checkout@v1
+      - uses: 40ants/setup-lisp@v1
+        with:
+          asdf-system: cl-info
+      - uses: 40ants/run-tests@v2-beta
+        with:
+          asdf-system: cl-info
+```
+
+The part, corresponding to an actionn call is:
+
+```yaml
+- uses: 40ants/setup-lisp@v1
+  with:
+    asdf-system: cl-info
+```
+
+If you remove `with` part, then action will skip the `ASDF` system
+installation.
+
+The last step in this workflow runs tests for the specified `ASDF`
+system. It is documented [here](https://40ants/run-tests).
+
+<a id='x-28DOCS-3A-40QL-FILE-20MGL-PAX-MINIMAL-3ASECTION-29'></a>
+
+## 3 Overriding qlfile
+
+Sometimes you might want to generate content of qlfile
+depending on matrix parameters. For example with matrix like this one:
+
+```yaml
+matrix:
+  os:
+    - ubuntu-latest
+    - macos-latest
+  quicklisp-dist:
+    - quicklisp
+    - ultralisp
+  lisp:
+    - sbcl-bin
+    - ccl-bin
+    - ecl
+```
+
+you might want to add an [ultralisp](https://ultralisp.org) source
+to the qlfile. Here is how this can be archived:
+
+```yaml
+env:
+  LISP: ${{ matrix.lisp }}
+  OS: ${{ matrix.os }}
+  QUICKLISP_DIST: ${{ matrix.quicklisp-dist }}
+
+steps:
+  - uses: actions/checkout@v1
+  - uses: 40ants/setup-lisp@v1
+    with:
+      asdf-system: cl-info
+      qlfile-template: |
+        {% ifequal quicklisp_dist "ultralisp" %}
+        dist ultralisp http://dist.ultralisp.org
+        {% endifequal %}
+
+        github mgl-pax svetlyak40wt/mgl-pax :branch mgl-pax-minimal
+```
+
+Here we see a few important things.
+
+1. We put into the env var the type of the quicklisp distribution we want to
+   our library to test against.
+
+2. We pass a multiline argument `qlfile-template` to the action.
+
+3. Template refers to `quicklisp_dist` to conditionally include a line
+   into `qlfile` when `quicklisp_dist == "ultralisp"`.
+
+You can refer any environment variable inside the `qlfile` templater.
+Also note, it is using [Djula](https://github.com/mmontone/djula)
+markup, similar to [Django](https://docs.djangoproject.com/en/3.1/topics/templates/)
+and [Jinja2](https://jinja.palletsprojects.com/).
+
+  [d1d0]: #x-28DOCS-3A-40QL-FILE-20MGL-PAX-MINIMAL-3ASECTION-29 "Overriding qlfile"
+  [f73c]: #x-28DOCS-3A-40FEATURES-20MGL-PAX-MINIMAL-3ASECTION-29 "What this action does for you?"
+  [ff56]: #x-28DOCS-3A-40TYPICAL-USAGE-20MGL-PAX-MINIMAL-3ASECTION-29 "A typical usage"
+
+* * *
+###### \[generated by [MGL-PAX](https://github.com/melisgl/mgl-pax)\]

docs.asd

@@ -0,0 +1,3 @@
+(defsystem "docs"
+    :class :package-inferred-system
+    :depends-on ("docs/docs"))

docs.lisp

@@ -0,0 +1,144 @@
+(defpackage #:docs
+  (:use #:cl)
+  (:nicknames #:docs/docs)
+  (:import-from #:mgl-pax-minimal
+                #:defsection
+                #:section))
+(in-package docs)
+
+
+(defsection @index (:title "GitHub Action to Setup Common Lisp for CI")
+  "
+This is a Github Action to setup Common Lisp, Roswell and Qlot.
+
+It is useful to call it before running tests or building docs
+for your Common Lisp libraries. Action encapsulates all steps
+necessary to make available [Roswell](https://github.com/roswell/roswell)
+and [Qlot](https://github.com/fukamachi/qlot) inside the Github CI.
+"
+  (@features section)
+  (@typical-usage section)
+  (@ql-file section))
+
+
+(defsection @features (:title "What this action does for you?")
+  "
+* It installs Roswell and all it's dependencies, doing right thing depending on
+  the operating system. It should work on Ubuntu, OSX and maybe Windows.
+* Upgrade ASDF to the latest version.
+* Installs Qlot.
+* Adds to `PATH` these directories: `~/.roswell/bin` and `.qlot/bin`
+* Creates `.qlot` by running `qlot install`. How to override content of the
+  `qlfile`, see \"Overriding qlfile\" section.
+* And finally, it can install a specified ASDF system and all it's dependencies.
+  But this step is optional.
+")
+
+
+(defsection @typical-usage (:title "A typical usage")
+  "
+Here is how a minimal GitHub Workflow might look like:
+
+```yaml
+name: 'CI'
+
+on:
+  push:
+    branches:
+      - 'main'
+      - 'master'
+  pull_request:
+
+jobs:
+  tests:
+    runs-on: ubuntu-latest
+    
+    strategy:
+      matrix:
+        lisp:
+          - sbcl-bin
+          - ccl-bin
+          
+    env:
+      LISP: ${{ matrix.lisp }}
+
+    steps:
+      - uses: actions/checkout@v1
+      - uses: 40ants/setup-lisp@v1
+        with:
+          asdf-system: cl-info
+      - uses: 40ants/run-tests@v2-beta
+        with:
+          asdf-system: cl-info
+```
+
+The part, corresponding to an actionn call is:
+
+```yaml
+- uses: 40ants/setup-lisp@v1
+  with:
+    asdf-system: cl-info
+```
+
+If you remove `with` part, then action will skip the ASDF system
+installation.
+
+The last step in this workflow runs tests for the specified ASDF
+system. It is documented [here](https://40ants/run-tests).
+")
+
+
+(defsection @ql-file (:title "Overriding qlfile")
+  "
+Sometimes you might want to generate content of qlfile
+depending on matrix parameters. For example with matrix like this one:
+
+```yaml
+matrix:
+  os:
+    - ubuntu-latest
+    - macos-latest
+  quicklisp-dist:
+    - quicklisp
+    - ultralisp
+  lisp:
+    - sbcl-bin
+    - ccl-bin
+    - ecl
+```
+
+you might want to add an [ultralisp](https://ultralisp.org) source
+to the qlfile. Here is how this can be archived:
+
+```yaml
+env:
+  LISP: ${{ matrix.lisp }}
+  OS: ${{ matrix.os }}
+  QUICKLISP_DIST: ${{ matrix.quicklisp-dist }}
+
+steps:
+  - uses: actions/checkout@v1
+  - uses: 40ants/setup-lisp@v1
+    with:
+      asdf-system: cl-info
+      qlfile-template: |
+        {% ifequal quicklisp_dist \"ultralisp\" %}
+        dist ultralisp http://dist.ultralisp.org
+        {% endifequal %}
+
+        github mgl-pax svetlyak40wt/mgl-pax :branch mgl-pax-minimal
+```
+
+Here we see a few important things.
+
+1. We put into the env var the type of the quicklisp distribution we want to
+   our library to test against.
+2. We pass a multiline argument `qlfile-template` to the action.
+3. Template refers to `quicklisp_dist` to conditionally include a line
+   into `qlfile` when `quicklisp_dist == \"ultralisp\"`.
+
+You can refer any environment variable inside the `qlfile` templater.
+Also note, it is using [Djula](https://github.com/mmontone/djula)
+markup, similar to [Django](https://docs.djangoproject.com/en/3.1/topics/templates/)
+and [Jinja2](https://jinja.palletsprojects.com/).
+")

qlfile

@@ -0,0 +1,4 @@
+dist ultralisp http://dist.ultralisp.org
+
+# Unless this patch is not merged:
+github mgl-pax svetlyak40wt/mgl-pax :branch mgl-pax-minimal

qlfile.lock

@@ -0,0 +1,12 @@
+("quicklisp" .
+ (:class qlot/source/dist:source-dist
+  :initargs (:distribution "http://beta.quicklisp.org/dist/quicklisp.txt" :%version :latest)
+  :version "2021-01-24"))
+("ultralisp" .
+ (:class qlot/source/dist:source-dist
+  :initargs (:distribution "http://dist.ultralisp.org" :%version :latest)
+  :version "20210215183000"))
+("mgl-pax" .
+ (:class qlot/source/github:source-github
+  :initargs (:repos "svetlyak40wt/mgl-pax" :ref nil :branch "mgl-pax-minimal" :tag nil)
+  :version "github-dc8a4585d7b9fe7b4c83a4bc2f338eab"))