Add tables

.github/workflows/docs-verify.yml

@@ -0,0 +1,32 @@
+name: Documentation
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize, ready_for_review]
+    paths:
+      - "docs/**"
+
+jobs:
+  # Just check that the build works and doesn't throw any errors
+  # The actual build and deployment is done on the main branch
+  # with another GitHub Actions workflow.
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+          working-directory: '${{ github.workspace }}/docs'
+
+      - name: Build with Jekyll
+        run: bundle exec jekyll build

.github/workflows/docs.yml

@@ -0,0 +1,69 @@
+# See the template here: https://github.com/just-the-docs/just-the-docs-template
+
+name: Documentation
+
+on:
+  push:
+    branches:
+      - "main"
+    paths:
+      - "docs/**"
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write # to deploy to Pages
+  id-token: write # to verify the deployment originates from an appropriate source
+
+# Allow one concurrent deployment
+concurrency:
+  group: "pages"
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.1'
+          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
+          cache-version: 0 # Increment this number if you need to re-download cached gems
+          working-directory: '${{ github.workspace }}/docs'
+
+      - name: Setup Pages
+        id: pages
+        uses: actions/configure-pages@v5
+
+      - name: Build with Jekyll
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
+
+      # Automatically creates an github-pages artifact used by the deployment job
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: "docs/_site/"
+
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -0,0 +1,41 @@
+name: Release package
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  releasepypi:
+    # see https://docs.pypi.org/trusted-publishers/using-a-publisher/
+    # and https://packaging.python.org/en/latest/tutorials/packaging-projects/#uploading-the-distribution-archives
+    name: Release to PyPI
+    runs-on: "ubuntu-latest"
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: 3.11
+          cache: 'pipenv'
+
+      - name: Run tests (one last time before release)
+        run: |
+          pip install pipenv
+          pipenv install --dev
+          pipenv run pip3 install --editable .
+          pipenv run pytest tests/
+
+      - name: Install build tooling
+        run: python3 -m pip install --upgrade build
+
+      - name: Build distributions
+        run: python3 -m build
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

.github/workflows/tests.yml

@@ -29,9 +29,12 @@ jobs:
           - name: Install dependencies (including dev dependencies)
             run: pipenv install --dev
 
+          - name: Install ResultWizard itself (as editable)
+            run: pipenv run pip3 install --editable .
+
           - name: Run Pytest
-            run: pipenv run pytest
+            run: pipenv run pytest tests/
 
 
 
-# [1] https://github.com/orgs/community/discussions/26366
+# [1] https://github.com/orgs/community/discussions/26366

.vscode/settings.json

@@ -19,13 +19,19 @@
     "pythonTestExplorer.testFramework": "pytest",
     "testExplorer.codeLens": true,
     "testExplorer.errorDecorationHover": true,
+    "python.testing.pytestArgs": [
+        "."
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
     //////////////////////////////////////
     // Files
     //////////////////////////////////////
     "files.exclude": {
         "**/__pycache__/": true,
         "**/*.egg-info/": true,
-        ".pytest_cache/": true
+        "**/.pytest_cache/": true,
+        "**/.jekyll-cache/": true
     },
     //////////////////////////////////////
     // Editor
@@ -56,6 +62,8 @@
     // Spell Checker
     //////////////////////////////////////
     "cSpell.words": [
+        "Commandifier",
+        "getcontext",
         "github",
         "ifthen",
         "ifthenelse",
@@ -64,20 +72,22 @@
         "newcommand",
         "normalsize",
         "pipenv",
+        "prec",
         "pydantic",
         "pylint",
         "pytest",
+        "resultwizard",
+        "scriptsize",
+        "scriptstyle",
+        "setcontext",
         "sigfigs",
         "siunitx",
         "Stringifier",
         "textbf",
         "texttt",
+        "TLDR",
         "uncert",
+        "uncerts",
         "usepackage"
-    ],
-    "python.testing.pytestArgs": [
-        "."
-    ],
-    "python.testing.unittestEnabled": false,
-    "python.testing.pytestEnabled": true
+    ]
 }

CHANGELOG.md

@@ -1,3 +1,3 @@
-# Changelog of ValueWizard
+# Changelog
 
-TODO
+👀 Nothing here yet

DEVELOPMENT.md

@@ -9,7 +9,7 @@ Getting ready:
 - [ ] Recommended VSCode extensions installed (especially the formatter. It should automatically format on every save!)
 - [ ] on branch `value-wizard` with latest commit pulled
 - [ ] Work through the `Setup` section below (especially to install the necessary dependencies)
-- [ ] Read the [`README.md`](https://github.com/paul019/ValueWizard/tree/value-wizard/src#code-structure) in the `src` folder (to get to know the code structure) & see our [feature list](https://github.com/paul019/ValueWizard/issues/16)
+- [ ] Read the [`README.md`](https://github.com/resultwizard/ResultWizard/tree/main/src#code-structure) in the `src` folder (to get to know the code structure) & see our [feature list](https://github.com/resultwizard/ResultWizard/issues/16)
 
 Verify that everything worked:
 - [ ] try to run the tests, see the instructions in [`tests/playground.py`](./tests/playground.py)
@@ -66,3 +66,15 @@ Also try adding `import pytest` as first line of a test file. Does it give you a
 Note that tests are also run on every commit via a GitHub action.
 
 In order to learn how to write the tests with pytest, start with the [`Get Started` guide](https://docs.pytest.org/en/8.0.x/getting-started.html#create-your-first-test). Probably also relevant: ["How to use fixtures"](https://docs.pytest.org/en/8.0.x/how-to/fixtures.html). There are lots of [How-to guides](https://docs.pytest.org/en/8.0.x/how-to/index.html) available.
+
+
+## Release to PyPI
+
+To release a new version to [PyPI](https://pypi.org/project/resultwizard/), do the following:
+
+- Create a PR that is going to get merged into `main`. Name it "Continuous Release <version number, e.g. 1.0.0-alpha.42>".
+- Make sure all tests pass and review the PR. Merge it into `main` via a *Merge commit*
+<br>(from `dev` to `main` always via *Merge commit*, not *Rebase* or *Squash and merge*).
+- On `main`, create a new release on GitHub. In this process (via the GitHub UI), create a new tag named "v<version number>", e.g. "v1.0.0-alpha.42".
+- The tag creation will trigger a GitHub action that builds and uploads the package to PyPI. As this action uses a special "release" environment, code owners have to approve this step.
+- Make sure the new version is available on PyPI [here](https://pypi.org/project/resultwizard/).

Pipfile

@@ -4,7 +4,6 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-plum-dispatch = "*"
 
 [dev-packages]
 pylint = "~=3.0"

README.md

@@ -1,17 +1,17 @@
 <div align="center">
-  <img src="https://github.com/paul019/ResultWizard/assets/37160523/8576038a-3867-470b-8f42-90b60ea92042" width="200px" />
+  <a href="https://resultwizard.github.io/ResultWizard/">
+    <img src="https://github.com/resultwizard/ResultWizard/assets/37160523/8576038a-3867-470b-8f42-90b60ea92042" width="120px" />
+  </a>
   <div align="center">
     <h3 align="center">ResultWizard</h3>
-    <p>Intelligent interface between Python-computed values and your LaTeX work</p>
+    <p><strong>Intelligent interface between Python-computed values and your LaTeX work</strong></p>
   </div>
 </div>
 
+Annoyed of having to copy around values from Python code to your LaTeX work? Think of `ResultWizard` as an interface between the two. Export any variables from Python including possible uncertainties and their units and directly reference them in your LaTeX document.
 
-## `ResultWizard` is ...
-
-- a
-- b
-
-
-## Usage
+> **Warning ⚠**
+> ResultWizard is still in its *alpha* stage. We're happy to receive your feedback, e.g. report any bugs. But note that the API might still change before we hit the first stable release 1.0.0.
 
+> **📄**
+> **For installation/usage/API, refer to our [documentation](https://resultwizard.github.io/ResultWizard/).**

TODO.md

@@ -0,0 +1,33 @@
+## Documentation
+
+**Things we should include in the documentation:**
+
+- an overview of what the goal of the project is with a small illustration where we sketch python code, the `results.tex` file and the LaTeX document and explain how they are connected
+- most common ways to use the library, but then also a comprehensive list of all possible ways to call `res` (preferable on a separate page of the documentation). How to guides for most common cases
+- ways to use the variable in LaTeX code, e.g. list all keys, tell users they should enter \resMyVariable[test] and then see the error message to find out what the possible keys are
+- passing in as string means exact value
+- how to specify the name of a variable. Numbers only allowed from 0 up to 1000. Special characters are stripped. Explain camel case etc.
+-> Explain that this has the great potential for loops: users can specify variables in a loop and use format strings, e.g. `wiz.res(f"my_variable_{i}", ...)`
+- how to pass in uncertainties. How to pass in one? What about systematic and statistical ones. What if I want to add my own name for the uncertainty? How can I control that output.
+- a list of all possible keys for `config_init` including their default values, e.g. `identifier`. In-depth explanation especially for sigfigs and decimal places and how they differ from respective fallback options
+- a hint that the output is completely customizable and that the user can change it with the `\sisetup{...}`, e.g. `\cdot` vs. `\times` for exponent, `separate-uncertainty=true` (!)
+- how to use the unit string. explain that strings from `siunitx` can be passed in, e.g. `\cm \per \N` etc. Explain how python raw strings can help, e.g. `r"\cm \per \N"` instead of having to do `\\cm` etc. all the time. However, `r'\\tesla'` will fail as the double backslash is treated a raw string and not as an escape character. Use `r'\tesla'` instead.
+- possible ways to print a result. Recommended: activate `print_auto`. Other way: call `print()` on result object. Users can also call `resVariable.to_latex_str()` to retrieve the LaTeX representation. This can be useful to plot the result in a matplotlib figure, e.g. the fit parameter of a curve fit.
+- Suggest some good initial configuration for Jupyter notebook, e.g. `print_auto=True` and `ignore_result_overwrite=True`.
+- Naming: we call it "uncertainty". Give a hint that others might also call it "error" interchangeably.
+- Jupyter Notebook tip to avoid
+
+```
+<api.printable_result.PrintableResult at 0x7f35beb20510>
+```
+as output. Instead append a `;` to the `wiz.res(...)` call and the output will be suppressed.
+
+- Use fuzzy search in IntelliSense to search for result names.
+
+
+
+## Other
+
+- Setup issue template and contribution guide. Clean up `DEVELOPMENT.md`.
+- Long-term: Ask real users what they really need in the scientific day-to-day life, see [here](https://github.com/resultwizard/ResultWizard/issues/9).
+- If user enters an uncertainty of `0.0`, don't just issue warning "Uncertainty must be positive", but also give a hint that the user might want to use a different caller syntax for `res` which does not even have the uncertainty as argument.