From a19eeb352f4a8b5f814370d3ee9b021ad3607358 Mon Sep 17 00:00:00 2001 From: Fernando Raya Date: Fri, 12 Apr 2024 06:43:42 +0200 Subject: [PATCH] Refurbish library - Update .gitignore (Fix #29) - Remove registry/ (Fix #25) - Add package description (Fix #24) - Add CI build and test (Fix #26) - Add documentation (skeleton) (Fix #27) - Update README (Fix #31) - Add CI to build documentation (Fix #28) I have made two GH actions. One is to build and check for link errors when a push or a pull request (PR) is made. The other on push only. If we try to deploy the documentation to GH pages on PR the action don't have permissions to write and fails. So I have done 'build-and-test.yml' so in a PR we can catch any error of broken links in the documentation and when the PR is accepted the push action will deploy the documentation to GH pages with 'build-and-deploy-documentation'. --- .github/dependabot.yml | 11 ++++ .../build-and-deploy-documentation.yml | 56 +++++++++++++++++++ .../build-and-test-documentation.yml | 35 ++++++++++++ .github/workflows/build-and-test.yml | 35 ++++++++++++ .gitignore | 20 ++++++- README.rst | 39 ++++++++----- documentation/Makefile | 20 +++++++ documentation/make.bat | 35 ++++++++++++ documentation/source/conf.py | 55 ++++++++++++++++++ documentation/source/index.rst | 23 ++++++++ dylan-package.json | 16 ++++++ registry/generic/command-interface | 1 - registry/generic/command-interface-demo | 1 - registry/generic/command-interface-test | 1 - registry/generic/tty | 1 - 15 files changed, 329 insertions(+), 20 deletions(-) create mode 100644 .github/dependabot.yml create mode 100644 .github/workflows/build-and-deploy-documentation.yml create mode 100644 .github/workflows/build-and-test-documentation.yml create mode 100644 .github/workflows/build-and-test.yml create mode 100644 documentation/Makefile create mode 100644 documentation/make.bat create mode 100644 documentation/source/conf.py create mode 100644 documentation/source/index.rst create mode 100644 dylan-package.json delete mode 100644 registry/generic/command-interface delete mode 100644 registry/generic/command-interface-demo delete mode 100644 registry/generic/command-interface-test delete mode 100644 registry/generic/tty diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..0d08e26 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file + +version: 2 +updates: + - package-ecosystem: "github-actions" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "weekly" diff --git a/.github/workflows/build-and-deploy-documentation.yml b/.github/workflows/build-and-deploy-documentation.yml new file mode 100644 index 0000000..c3d18af --- /dev/null +++ b/.github/workflows/build-and-deploy-documentation.yml @@ -0,0 +1,56 @@ +name: Build and deploy documentation + +on: + push: + # all branches + paths: + - 'documentation/**' + + # This enables the Run Workflow button on the Actions tab. + workflow_dispatch: + +# https://github.com/JamesIves/github-pages-deploy-action#readme +permissions: + contents: write + +# Set DYLAN environment variable to GITHUB_WORKSPACE so packages are +# installed in ../../_packages relative to documentation's Makefile +env: + DYLAN: ${{ github.workspace }} + +jobs: + + build-and-deploy: + runs-on: ubuntu-latest + steps: + + - name: Checkout code + uses: actions/checkout@v4 + + - name: Check links + uses: addnab/docker-run-action@v3 + with: + image: ghcr.io/fraya/dylan-docs + options: -v ${{ github.workspace }}/documentation:/docs + run: make linkcheck + + - name: Build docs with Furo theme + uses: addnab/docker-run-action@v3 + with: + image: ghcr.io/fraya/dylan-docs + options: -v ${{ github.workspace }}/documentation:/docs + run: make html + + - name: Upload html artifact + uses: actions/upload-artifact@v4 + with: + name: command-interface-html + path: documentation/build/html/ + + - name: Bypassing Jekyll on GH Pages + run: sudo touch documentation/build/html/.nojekyll + + - name: Deploy docs to GH pages + uses: JamesIves/github-pages-deploy-action@v4 + with: + folder: documentation/build/html diff --git a/.github/workflows/build-and-test-documentation.yml b/.github/workflows/build-and-test-documentation.yml new file mode 100644 index 0000000..9565dca --- /dev/null +++ b/.github/workflows/build-and-test-documentation.yml @@ -0,0 +1,35 @@ +name: Build and test documentation + +on: + push: + # all branches + paths: + - 'documentation/**' + pull_request: + # all branches + paths: + - 'documentation/**' + + # This enables the Run Workflow button on the Actions tab. + workflow_dispatch: + +# Set DYLAN environment variable to GITHUB_WORKSPACE so packages are +# installed in ../../_packages relative to documentation's Makefile +env: + DYLAN: ${{ github.workspace }} + +jobs: + + build-and-test: + runs-on: ubuntu-latest + steps: + + - name: Checkout code + uses: actions/checkout@v4 + + - name: Check links + uses: addnab/docker-run-action@v3 + with: + image: ghcr.io/fraya/dylan-docs + options: -v ${{ github.workspace }}/documentation:/docs + run: make linkcheck diff --git a/.github/workflows/build-and-test.yml b/.github/workflows/build-and-test.yml new file mode 100644 index 0000000..4b730b2 --- /dev/null +++ b/.github/workflows/build-and-test.yml @@ -0,0 +1,35 @@ +name: Build and test + +on: + push: + # all branches + pull_request: + # all branches + + # This enables the Run Workflow button on the Actions tab. + workflow_dispatch: + +jobs: + build-and-test: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install Opendylan + uses: dylan-lang/install-opendylan@v3 + + - name: Download dependencies + run: dylan update + + - name: Build tests + run: dylan build command-interface-test + + - name: Run tests + run: _build/bin/command-interface-test --progress none --report surefire > _build/TEST-command-interface.xml + + - name: Publish Test Report + if: success() || failure() + uses: mikepenz/action-junit-report@v4 + with: + report_paths: '**/_build/TEST-*.xml' diff --git a/.gitignore b/.gitignore index e35d885..46d23fa 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,19 @@ -_build +# backup files +*~ +*.bak +.DS_Store + +# project file +*.hdp + +# documentation build directory +build/ + +# compiler build directory +_build/ + +# dylan tool package cache +_packages/ + +# package registry folder +registry/ \ No newline at end of file diff --git a/README.rst b/README.rst index 3320610..f06eec7 100644 --- a/README.rst +++ b/README.rst @@ -1,33 +1,44 @@ Command Interface System ======================== +|Build status| + +.. image:: https://github.com/dylan-lang/command-interface/actions/workflows/build-and-test.yml/badge.svg + :target: https://github.com/dylan-lang/command-interface/actions/workflows/build-and-test.yml + +|Documentation| + +.. image:: https://github.com/dylan-lang/command-interface/actions/workflows/build-and-deploy-documentation.yml/badge.svg + :target: https://github.com/dylan-lang/command-interface/actions/workflows/build-and-deploy-documentation.yml + This is a system for building command-driven interfaces in Dylan. It can currently be used to declaratively design terminal-based command interfaces, commonly called shells or CLIs. -We also strive to implement graphical command interfaces in a -similar manner to Symbolics Genera, including support for -full graphical and markup output. +We also strive to implement graphical command interfaces in a similar +manner to `Symbolics Genera +`_, including +support for full graphical and markup output. Compiling --------- -All dependencies are in `Open Dylan`_ itself. +Update library dependencies:: + + dylan update -Just build with:: +Build the library, tests and demo with:: - $ dylan-compiler -build command-interface + dylan build --all -There also is a demo:: +Run the demo:: - $ dylan-compiler -build command-interface-demo - $ _build/bin/command-interface-demo + _build/bin/command-interface-demo -As well as some tests:: +And the tests:: - $ dylan-compiler -build command-interface-test - $ _build/bin/command-interface-test + _build/bin/command-interface-test Completion in bash ------------------ @@ -39,11 +50,9 @@ interactive shell and from the system shell. To enable this feature you need to load the shell snippet printed by the following command into your shell:: - $ _build/bin/command-interface-demo bashcomplete + _build/bin/command-interface-demo bashcomplete Once you do this you can complete and execute all commands that would be available inside the shell. This feature is automatically available to library users. - -.. _Open Dylan: https://github.com/dylan-lang/opendylan diff --git a/documentation/Makefile b/documentation/Makefile new file mode 100644 index 0000000..d0c3cbf --- /dev/null +++ b/documentation/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) diff --git a/documentation/make.bat b/documentation/make.bat new file mode 100644 index 0000000..747ffb7 --- /dev/null +++ b/documentation/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 diff --git a/documentation/source/conf.py b/documentation/source/conf.py new file mode 100644 index 0000000..0666942 --- /dev/null +++ b/documentation/source/conf.py @@ -0,0 +1,55 @@ +# 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 + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. + +import os +import sys + +sys.path.insert(0, os.path.abspath('../../_packages/sphinx-extensions/current/src/sphinxcontrib')) + +import dylan.themes as dylan_themes + +# -- Project information ----------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information + +project = 'Command interface' +copyright = '2024, Ingo Albrecht' +author = 'Ingo Albrecht' +release = '0.1.0' + +# -- General configuration --------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration + +extensions = [ + 'dylan.domain', + 'sphinx.ext.intersphinx' +] + +templates_path = ['_templates'] + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path. +exclude_patterns = ['_build'] + +# This makes it so that each document doesn't have to use +# .. default-domain:: dylan +# but they probably should anyway, so that they can be built separately +# without depending on this top-level config file. +primary_domain = 'dylan' + +# -- Options for HTML output ------------------------------------------------- +# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output + +html_theme = 'furo' +html_static_path = ['_static'] + +# Ignore certification verification +tls_verify = False diff --git a/documentation/source/index.rst b/documentation/source/index.rst new file mode 100644 index 0000000..2a2b1bf --- /dev/null +++ b/documentation/source/index.rst @@ -0,0 +1,23 @@ +Welcome to Command interface's documentation! +============================================= + +.. toctree:: + :maxdepth: 2 + :caption: Contents: + +This is a system for building command-driven interfaces in Dylan. + +It can currently be used to declaratively design terminal-based +command interfaces, commonly called shells or CLIs. + +We also strive to implement graphical command interfaces in a similar +manner to Symbolics Genera, including support for full graphical and +markup output. + + +Indices and tables +================== + +* :ref:`genindex` +* :ref:`modindex` +* :ref:`search` diff --git a/dylan-package.json b/dylan-package.json new file mode 100644 index 0000000..07bc866 --- /dev/null +++ b/dylan-package.json @@ -0,0 +1,16 @@ +{ + "name": "command-interface", + "description": "Interactive command interface system for Dylan", + "keywords": [ "command-line" ], + "version": "0.1.1", + "url": "https://github.com/dylan-lang/command-interface", + "category" : "utilities", + "contact": "dylan-lang@googlegroups.com", + "dependencies": [], + "dev-dependencies": [ + "testworks@3.2.0", + "sphinx-extensions@0.2.0" + ], + "license": "MIT", + "license-url": "https://opensource.org/license/mit" +} diff --git a/registry/generic/command-interface b/registry/generic/command-interface deleted file mode 100644 index c3032c0..0000000 --- a/registry/generic/command-interface +++ /dev/null @@ -1 +0,0 @@ -abstract://dylan/command-interface/command-interface.lid diff --git a/registry/generic/command-interface-demo b/registry/generic/command-interface-demo deleted file mode 100644 index 2b306a3..0000000 --- a/registry/generic/command-interface-demo +++ /dev/null @@ -1 +0,0 @@ -abstract://dylan/examples/demo/command-interface-demo.lid diff --git a/registry/generic/command-interface-test b/registry/generic/command-interface-test deleted file mode 100644 index f57f0d3..0000000 --- a/registry/generic/command-interface-test +++ /dev/null @@ -1 +0,0 @@ -abstract://dylan/tests/command-interface-test.lid diff --git a/registry/generic/tty b/registry/generic/tty deleted file mode 100644 index e356742..0000000 --- a/registry/generic/tty +++ /dev/null @@ -1 +0,0 @@ -abstract://dylan/tty/tty.lid