Squashed commit of the following:

commit e8d3467 Author: Splines <37160523+Splines@users.noreply.github.com> Date: Fri Sep 6 19:02:36 2024 +0200 Implement new `wiz.res()` API (#41) * Remove plum as dependency * Implement new `wiz.res()` API (see #33) * Fix errors in error messages * Use consistent comment format in error messages * Add docstrings to `wiz.res()` * Add missing `int` type for uncertainties * Add PrintableResult to res() method signature * Rename `uncert` to `uncerts` (plural) commit cc6bf5b Author: paul019 <39464035+paul019@users.noreply.github.com> Date: Sat Apr 27 20:25:54 2024 +0200 Improve wording: use `uncertainty` instead of `error` (#43) * Remove spaces in units * Detect percent as unit in console stringifier * Replace error by uncert * Undo unwanted changes * Replace error by uncertainty in various places commit 62c34a5 Author: Splines <37160523+Splines@users.noreply.github.com> Date: Sat Apr 27 19:45:34 2024 +0200 Add missing `site.baseurl` to relative links (#52) commit f5e0007 Author: Splines <37160523+Splines@users.noreply.github.com> Date: Sat Apr 27 19:45:19 2024 +0200 Truncate Readme & refer to documentation (#51) * Truncate Readme & refer to documentation * Remove GitHub-flavored markdown Otherwise, it won't be rendered correctly on PyPI. * Make Readme image clickable (points to docs) commit 7af242c Author: Splines <37160523+Splines@users.noreply.github.com> Date: Wed Apr 24 17:56:11 2024 +0200 Add first version of docs (#37) * Init _Just the docs_ basic structure * Add Jupyter-related items to TODO * Add GitHub pages docs workflow * Add 404 page * Add landing page of documentation * Add LaTeX rendered output * Add quickstart & backbone for other pages * Add `export()` & siunitx troubleshooting * Add docs for `wiz.res()` * Add `wiz.res()` tip for multiple occurrences * Add config options & siunitx tips * Improve Jupyter section & add "Is this really for me?" * Add about page * Add table of contents (TOC) back to about page * Add docs build workflow for PRs * Specify correct cwd for docs workflow * Fix remaining docs workflow errors * Add tip for how to suppress output in JupyterNotebook. This fixes #44. commit 63f2a6b Author: Splines <37160523+Splines@users.noreply.github.com> Date: Mon Apr 22 23:31:50 2024 +0200 Update GitHub URLs to point to new repo location (#47)
resultwizard · Sep 9, 2024 · 1f775ff · 1f775ff
1 parent efa0329
commit 1f775ff
Show file tree

Hide file tree

Showing 38 changed files with 1,156 additions and 331 deletions.
diff --git a/.github/workflows/docs-verify.yml b/.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
diff --git a/.github/workflows/docs.yml b/.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
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -30,7 +30,8 @@
     "files.exclude": {
         "**/__pycache__/": true,
         "**/*.egg-info/": true,
-        ".pytest_cache/": true
+        "**/.pytest_cache/": true,
+        "**/.jekyll-cache/": true
     },
     //////////////////////////////////////
     // Editor
@@ -86,6 +87,7 @@
         "texttt",
         "TLDR",
         "uncert",
+        "uncerts",
         "usepackage"
     ]
 }
diff --git a/DEVELOPMENT.md b/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/ResultWizard/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/ResultWizard/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)

diff --git a/Pipfile b/Pipfile
@@ -4,7 +4,6 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-plum-dispatch = "~=2.3"
 
 [dev-packages]
 pylint = "~=3.0"

diff --git a/Pipfile.lock b/Pipfile.lock
diff --git a/README.md b/README.md
@@ -1,156 +1,17 @@
 <div align="center">
-  <img src="https://github.com/paul019/ResultWizard/assets/37160523/8576038a-3867-470b-8f42-90b60ea92042" width="120px" />
+  <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><strong>Intelligent interface between Python-computed values and your LaTeX work</strong></p>
   </div>
 </div>
 
-> **Warning ⚠**
-> ResultWizard is currently fully functional but still in its *alpha* stage. We're happy to receive your feedback. Basic usage is as follows. A more comprehensive documentation will be available as soon as the package is stable.
-
-
-## Installation & basic usage
-Install the package via pip.
-
-```sh
-pip install resultwizard
-```
-
-Then you can use `ResultWizard` in your Python code:
-
-```python
-import resultwizard as wiz
-wiz.config_init(print_auto=True)
-
-# your complex calculations
-# ...
-value = 42.0
-uncertainty = 3.14
-wiz.res("length atom", value, uncertainty, r"\per\mm\cubed")
-# There are many more ways to call wiz.res(...), try to use
-# IntelliSense in your IDE to see all possibilities.
-# A more in-depth documentation will follow in next releases.
-
-# Export the result to a LaTeX file. Provide a path as string
-# where the file should be saved.
-wiz.export("./results.tex")
-```
-
-Now add the following line to your LaTeX document right before `\begin{document}`:
-
-```latex
-% assuming that `results.tex` is located in the same directory
-% as your LaTeX document
-\input{./results.tex}
-
-\begin{document}
-...
-```
-
-Note that `ResultWizard` requires the following LaTeX packages: [`siunitx`](https://ctan.org/pkg/siunitx) and [`ifthen`](https://ctan.org/pkg/ifthen). They are imported in the `results.tex` file via `\usepackage{...}` statements. The package `ifthen` is always present in a LaTeX distribution. You may have to install the `siunitx` package, which is a widely used package in the scientific community to typeset units, e.g. you can use strings like `\kg\per\cm`.
-
-You can now go ahead and **use the variable in your LaTeX document** in any math environment, e.g.:
-
-```latex
-\begin{align}
-    \resLengthAtom
-\end{align}
-```
-
-You can also only use a specific part of the result, e.g. the unit, the value itself etc. (try to use a random key like `\resLengthAtom[x]` and compile your LaTeX document to see more options).
-
-```latex
-\begin{align}
-    \resLengthAtom[unit]
-\end{align}
-```
-
----
-
-If your LaTeX document does not compile, try to set
-
-```python
-wiz.config_init(siunitx_fallback=True)
-```
-
-in your `ResultWizard` configuration. If the LaTeX document compiles after this, you have an older version of `siunitx` installed. We recommend to upgrade the package to at least version `v3.1.0` to be able to fully customize the output of the result in your LaTeX document via `\sisetup{...}`. See the troubleshooting section down below for more information.
-
-
-## Troubleshooting: LaTeX doesn't build
-
-If your LaTeX document doesn't build, there might be several reasons. Try to find out what's wrong by looking at the log file of your LaTeX compiler (sometimes you have to scroll way up to find the error responsible for the failing build). Also open the `results.tex` file to see if your editor/IDE shows any errors there. You might encounter one of the following errors:
-
-<details>
+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.
 
-<summary><strong>Package siunitx: Invalid number.</strong></summary>
-
-TL;DR: You have an **old version of `siunitx`**. Please update it or use the `siunitx_fallback` option in the `config_init` method.
-
-In version [`v3.1.0 (2022-04-25)`](https://github.com/josephwright/siunitx/blob/main/CHANGELOG.md#v310---2022-04-25), `siunitx` introduced "support for multiple uncertainty values in both short and long form in input". We make use of this feature in `ResultWizard`.
-
-Unfortunately, it may be the case that you're using an older version of `siunitx`. Especially if you've installed LaTeX via a package manager (e.g. you installed `siunitx` via `sudo apt install texlive-science`). To determine your version, include the following line in your LaTeX document:
-
-```latex
-\listfiles % add this before \begin{document}
-```
-
-Then, compile your document and check the log for the version of `siunitx`. If it's older than `v3.1.0 (2022-04-25)`, don't despair. We have two solutions for you:
-
-**Solution 1: Don't update `siunitx` and stick with your old version**
-
-Sure, fine, we won't force you to update `siunitx` (although we'd recommend it). To keep using your old version, specify the following key in the `config_init` method:
-
-```python
-wiz.config_init(siunitx_fallback=True)
-```
-
-Note that with this "solution", you won't be able to fully customize the output of the result in your LaTeX document. For example, we will use a `±` between the value and the uncertainty, e.g. `3.14 ± 0.02`. You won't be able to change this in your `sisetup` by doing:
-
-```latex
-\sisetup{separate-uncertainty=false}
-```
-
-to get another format like `3.14(2)`. There are also some [other `siunitx` options](https://texdoc.org/serve/siunitx/0) that won't work with `ResultWizard`, e.g. `exponent-product`. If you're fine with this, go ahead and use the `siunitx_fallback` option. If not, consider updating `siunitx` to at least version `v3.1.0`.
-
-**Solution 2: Update `siunitx` (recommended)**
-
-How the update process works depends on your LaTeX distribution and how you installed it. E.g. you might be using `TeX Live` on `Ubuntu` and installed packages via `apt`, e.g. `sudo apt install texlive-science` (which includes the LaTeX `siunitx`). These pre-built packages are often outdated, e.g. for Ubuntu 22.04 LTS (jammy), the `siunitx` package that comes with the `texlive-science` package is `3.0.4`. Therefore, you might have to update `siunitx` manually. See an overview on how to install individual LaTeX packages on Linux [here](https://tex.stackexchange.com/a/73017/).
-
-A quick solution might be to simply install a new version of `siunitx` manually to your system. There's a great and short Ubuntu guide on how to install LaTeX packages manually [here](https://help.ubuntu.com/community/LaTeX#Installing_packages_manually). The following commands are based on this guide. We will download the version `3.1.11 (2022-12-05)` from GitHub (this is the last version before `3.2` where things might get more complicated to install) and install it locally. Nothing too fancy. Execute the following commands in your terminal:
-
-```sh
-# Install "unzip", a tool to extract zip files
-sudo apt install unzip
-
-# Download v3.1.11 of siunitx from GitHub
-curl -L https://github.com/josephwright/siunitx/releases/download/v3.1.11/siunitx-ctan.zip > siunitx-ctan-3.1.11.zip
-
-# Unzip the file
-unzip ./siunitx-ctan-3.1.11.zip
-cd siunitx/
-
-# Run LaTeX on the .ins file to produce a usable .sty file
-# (The .sty file is needed when you use \usepackage{siunitx}
-# in your LaTeX document)
-latex siunitx.ins
-
-# Create a new directory in your home directory
-# to store the new package .sty file
-mkdir -p ~/texmf/tex/latex/siunitx
-cp siunitx.sty ~/texmf/tex/latex/siunitx/
-
-# Make LaTeX recognize the new package by pointing it to the new directory
-texhash ~/texmf/
-
-# 🙌 Done. Try to rebuild your LaTeX document again.
-
-# If you don't wan't the new siunitx version anymore, just run the following
-# command to remove the .sty file. LaTeX will then use the version of siunitx
-# it finds somewhere else in your system.
-rm ~/texmf/tex/latex/siunitx/siunitx.sty
-```
-
-Compiling your latex document again, you should see version `v3.1.11` of `siunitx` in the log file. And it should build, yeah 🎉. Don't forget to remove the `\listfiles` from your LaTeX document to avoid cluttering your log file (which is ironic for LaTeX, we know).
+> **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.
 
-</details>
+> **📄**
+> **For installation/usage/API, refer to our [documentation](https://resultwizard.github.io/ResultWizard/).**
diff --git a/TODO.md b/TODO.md
@@ -10,14 +10,24 @@
 -> 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, etc.
+- 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/paul019/ResultWizard/issues/9).
+- 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.