Store source code in repo

.githooks/pre-commit

@@ -0,0 +1,16 @@
+#!/bin/sh
+# this shell script is stored as .githooks/pre-commit
+
+UID=$(id -u)
+
+echo 'Check entangled files are up to date'
+
+# Entangle Markdown to source code and store the output
+LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md 2>&1 > /dev/null)
+# Parse which filenames have been written from output
+FILES=$(echo $LOG | perl -ne 'print $1,"\n" if /^Writing \`(.*)\`./')
+[ -z "$FILES" ] && exit 0
+echo $FILES
+
+echo 'Adding written files to commit'
+echo $FILES | xargs git add

.github/workflows/main.yml

@@ -8,100 +8,111 @@ on: [push, pull_request]
 
 # A workflow run is made up of one or more jobs that can run sequentially or in parallel
 jobs:
+  entangle:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Check all entangled files are in sync with Markdown
+        run: make check
   cpp:
     # The type of runner that the job will run on
     runs-on: ubuntu-latest
 
     # Steps represent a sequence of tasks that will be executed as part of the job
     steps:
-    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-    - uses: actions/checkout@v2
-
-    # Should not be needed anymore when https://github.com/NLESC-JCER/cpp2wasm/issues/1 is fixed
-    - name: Generate source code
-      uses: docker://nlesc/pandoc-tangle:0.5.0
-      with:
-        args: --preserve-tabs README.md INSTALL.md
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
 
-    - name: Run C++ examples
-      run: make test-cli test-cgi
+      - name: Run C++ examples
+        run: make test-cli test-cgi
   python:
-      # The type of runner that the job will run on
+    # The type of runner that the job will run on
+    name: Python ${{ matrix.python-version }}
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: [3.6, 3.7, 3.8]
+      fail-fast: true
     # Redis is needed for Celery
     services:
       redis:
         image: redis
         ports:
           - 6379:6379
     steps:
-    # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
-    - uses: actions/checkout@v2
-
-    # Should not be needed anymore when https://github.com/NLESC-JCER/cpp2wasm/issues/1 is fixed
-    - name: Generate source code
-      uses: docker://nlesc/pandoc-tangle
-      with:
-        args: --preserve-tabs README.md INSTALL.md
-
-    - uses: actions/setup-python@v1
-      with:
-        python-version: '3.x' # Version range or exact version of a Python version to use, using SemVer's version range syntax
-        architecture: 'x64' # optional x64 or x86. Defaults to x64 if not specified
-
-    - name: Install Python dependencies
-      run: make py-deps && pip install httpie
-
-    - name: Run Python example
-      run: make test-py
-
-    - name: Start web application in background
-      run: make run-webapp &
-
-    - name: Test web application
-      run: http --ignore-stdin -f localhost:5001 epsilon=0.001 guess=-20
-
-    - name: Start web service in background
-      run: make run-webservice &
-
-    - name: Test web service
-      run: make test-webservice
-
-    - name: Start Celery web app in background
-      run: make run-celery-webapp &
-
-    - name: Start Celery worker in background
-      run: |
-        cd src/py
-        PYTHONPATH=$PWD/../.. celery -A tasks worker &
-        cd ../..
-
-    - name: Test Celery web app
-      run: |
-        http --ignore-stdin -hf localhost:5000 epsilon=0.001 guess=-20 | tee response.txt
-        # Parse result url from response
-        RESULT_URL=$(cat response.txt |grep Location |awk '{print $2}')
-        sleep 2
-        http --ignore-stdin $RESULT_URL
+      # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
+      - uses: actions/checkout@v2
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v1
+        with:
+          python-version: ${{ matrix.python-version }}
+          architecture: "x64"
+
+      - name: Which Python
+        run: which python
+
+      - name: Install Python dependencies
+        run: make py-deps && pip install httpie
+
+      - name: Run Python example
+        run: make test-py
+
+      - name: Start web application in background
+        run: make run-webapp 2>&1 | tee ./run-webapp.log &
+
+      - name: Test web application
+        run: http --ignore-stdin -f localhost:5001 epsilon=0.001 guess=-20
+
+      - name: Start web service in background
+        run: make run-webservice 2>&1 | tee ./run-webservice.log &
+
+      - name: Test web service
+        run: make test-webservice
+
+      - name: Start Celery web app in background
+        run: make run-celery-webapp 2>&1 | tee ./run-celery-webapp.log  &
+
+      - name: Start Celery worker in background
+        run: |
+          cd src/py
+          PYTHONPATH=$PWD/../.. celery -A tasks worker 2>&1 | tee ./run-celery-worker.log &
+          cd ../..
+
+      - name: Test Celery web app
+        run: |
+          http --ignore-stdin -hf localhost:5000 epsilon=0.001 guess=-20 | tee response.txt
+          # Parse result url from response
+          RESULT_URL=$(cat response.txt |grep Location |awk '{print $2}')
+          sleep 2
+          http --ignore-stdin $RESULT_URL
+
+      - name: Upload log of services
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v2
+        with:
+          name: service-logs
+          path: ./run-*.log
   wasm:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v2
 
-      # Should not be needed anymore when https://github.com/NLESC-JCER/cpp2wasm/issues/1 is fixed
-      - name: Generate source code
-        uses: docker://nlesc/pandoc-tangle
-        with:
-          args: --preserve-tabs README.md INSTALL.md
-
       - name: Install emscripten
         uses: mymindstorm/setup-emsdk@v4
 
       - name: Build WebAssembly module
         run: make build-wasm
 
       - name: Start web server for hosting files in background
-        run: make host-files &
+        run: make host-files 2>&1 | tee ./web-server.log &
 
       - name: Run tests
         run: make test-wasm
+
+      - name: Upload log of web server
+        if: ${{ always() }}
+        uses: actions/upload-artifact@v2
+        with:
+          name: web-server-log
+          path: ./web-server.log

.gitignore

@@ -4,3 +4,13 @@ __pycache__/
 cypress/plugins
 cypress/support
 cypress/videos
+
+# Ignore compiled files
+bin/newtonraphson.exe
+src/py/newtonraphsonpy.*.so
+apache2/cgi-bin/newtonraphson
+src/js/newtonraphsonwasm.js
+src/js/newtonraphsonwasm.wasm
+
+# Ignore entangled db
+.entangled/db.sqlite

.zenodo.json

@@ -0,0 +1,6 @@
+{
+   "license": {
+      "id": "Apache-2.0"
+   }, 
+   "title": "Guide to make C++ available as a web application"
+}

CONTRIBUTING.md

@@ -0,0 +1,180 @@
+# Contributing
+
+- [Contributing](#contributing)
+  - [Types of Contributions](#types-of-contributions)
+    - [Report Bugs](#report-bugs)
+    - [Fix Bugs](#fix-bugs)
+    - [Implement Features](#implement-features)
+    - [Submit Feedback](#submit-feedback)
+  - [Get Started!](#get-started)
+  - [Pull Request Guidelines](#pull-request-guidelines)
+  - [Tips](#tips)
+    - [Generating code from Markdown](#generating-code-from-markdown)
+    - [Generate code from Markdown and vice versa](generate-code-from-markdown-and-vice-versa)
+    - [Generate code from Markdown on commit](#generate-code-from-markdown-on-commit)
+  - [New release](#new-release)
+
+Contributions are welcome, and they are greatly appreciated! Every little bit
+helps, and credit will always be given.
+
+You can contribute in many ways:
+
+## Types of Contributions
+
+### Report Bugs
+
+Report bugs at [https://github.com/NLESC-JCER/cpp2wasm/issues](https://github.com/NLESC-JCER/cpp2wasm/issues).
+
+If you are reporting a bug, please include:
+
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
+
+### Fix Bugs
+
+Look through the GitHub issues for bugs. Anything tagged with "bug" and "help
+wanted" is open to whoever wants to implement it.
+
+### Implement Features
+
+Look through the GitHub issues for features. Anything tagged with "enhancement"
+and "help wanted" is open to whoever wants to implement it.
+
+### Submit Feedback
+
+The best way to send feedback is to file an issue at [https://github.com/NLESC-JCER/cpp2wasm/issues](https://github.com/NLESC-JCER/cpp2wasm/issues).
+
+If you are proposing a feature:
+
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
+- Remember that this is a volunteer-driven project, and that contributions
+  are welcome :)
+
+## Get Started!
+
+Ready to contribute? Here's how to set up `cpp2wasm` for local development.
+
+1. Fork the `cpp2wasm` repo on GitHub.
+2. Clone your fork locally::
+
+    ```shell
+    git clone git@github.com:your_name_here/cpp2wasm.git
+    ```
+
+3. Install the dependencies as listed in [INSTALL.md#dependencies](INSTALL.md#dependencies).
+
+4. Create a branch for local development::
+
+    ```shell
+    git checkout -b name-of-your-bugfix-or-feature
+    ```
+
+    Now you can make your changes locally.
+
+5. Write tests where possible. Writing tests should be done in a literate way in [TESTING.md](TESTING.md)
+
+6. When you're done making changes, make sure the Markdown and source code files are entangled with.
+
+    ```shell
+    make entangle
+    ```
+
+7. Commit your changes and push your branch to GitHub::
+
+    ```shell
+    git add .
+    git commit -m "Your detailed description of your changes."
+    git push origin name-of-your-bugfix-or-feature
+    ```
+
+8. Submit a pull request through the GitHub website.
+
+## Pull Request Guidelines
+
+Before you submit a pull request, check that it meets these guidelines:
+
+1. The pull request should include tests.
+2. If the pull request adds functionality, the docs should be updated. Put
+   your new functionality into a function with a docstring, and add the
+   feature to the list in README.rst.
+3. The pull request should work for Python 3.5, 3.6, 3.7 and 3.8, and for PyPy. Check
+   https://travis-ci.com/{{ cookiecutter.github_username }}/cpp2wasm/pull_requests
+   and make sure that the tests pass for all supported Python versions.
+
+## Tips
+
+## Generating code from Markdown
+
+The [Entangled - Pandoc filters](https://github.com/entangled/filters) Docker image can be used to generate source code files from the Markdown files.
+
+```{.awk #pandoc-tangle}
+docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md
+```
+
+## Generate code from Markdown and vice versa
+
+Use Entangled deamon to convert code blocks in Markdown to and from source code files.
+Each time a Markdown code block is changed the source code files will be updated.
+Each time a source code file is changed the code blocks in the Markdown files will be updated.
+
+1. Install [entangled](https://github.com/entangled/entangled)
+2. Run entangled daemon with
+
+```shell
+entangled daemon
+```
+
+### Generate code from Markdown on commit
+
+To automatically generate code from Markdown on each commit, initialize the git hook with.
+
+```shell
+make init-git-hook
+```
+
+The rest of this section describes how the git hook works.
+
+The pre-commit hook script runs entangle using Docker and adds newly written files to the current git commit.
+
+```{.awk file=.githooks/pre-commit}
+#!/bin/sh
+# this shell script is stored as .githooks/pre-commit
+
+UID=$(id -u)
+
+echo 'Check entangled files are up to date'
+
+# Entangle Markdown to source code and store the output
+LOG=$(docker run --rm --user ${UID} -v ${PWD}:/data nlesc/pandoc-tangle:0.5.0 --preserve-tabs *.md 2>&1 > /dev/null)
+# Parse which filenames have been written from output
+FILES=$(echo $LOG | perl -ne 'print $1,"\n" if /^Writing \`(.*)\`./')
+[ -z "$FILES" ] && exit 0
+echo $FILES
+
+echo 'Adding written files to commit'
+echo $FILES | xargs git add
+```
+
+The hook must be made executable with
+
+```{.awk #hook-permission}
+chmod +x .githooks/pre-commit
+```
+
+The git hook can be enabled with
+
+```{.awk #init-git-hook}
+git config --local core.hooksPath .githooks
+```
+
+(`core.hooksPath` config is available in git version >= 2.9)
+
+## New release
+
+A reminder for the maintainers on how to create a new release.
+
+1. Make sure all your changes are committed.
+1. Create a GitHub release
+1. Check and fix author list on Zenodo