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.

.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

.vscode/settings.json

@@ -30,7 +30,8 @@
     "files.exclude": {
         "**/__pycache__/": true,
         "**/*.egg-info/": true,
-        ".pytest_cache/": true
+        "**/.pytest_cache/": true,
+        "**/.jekyll-cache/": true
     },
     //////////////////////////////////////
     // Editor

TODO.md

@@ -10,11 +10,21 @@
 -> 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
 

docs/.gitignore

@@ -0,0 +1,12 @@
+# These are directly copied from Jekyll's first-party docs on `.gitignore` files:
+# https://jekyllrb.com/tutorials/using-jekyll-with-bundler/#commit-to-source-control
+
+# Ignore the default location of the built site, and caches and metadata generated by Jekyll
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+# Ignore folders generated by Bundler
+.bundle/
+vendor/

docs/404.html

@@ -0,0 +1,26 @@
+---
+permalink: /404.html
+layout: default
+---
+
+<style type="text/css" media="screen">
+    .container {
+        margin: 10px auto;
+        max-width: 600px;
+        text-align: center;
+    }
+
+    h1 {
+        margin: 30px 0;
+        font-size: 4em;
+        line-height: 1;
+        letter-spacing: -1px;
+    }
+</style>
+
+<div class="container">
+    <h1>404</h1>
+
+    <p><strong>Page not found 😥</strong></p>
+    <p>The requested page could not be found.</p>
+</div>

docs/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.3" # installed by `gem jekyll`
+gem "just-the-docs", "0.8.1" # pinned to the current release

docs/Gemfile.lock

@@ -0,0 +1,82 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    colorator (1.1.0)
+    concurrent-ruby (1.2.3)
+    em-websocket (0.5.3)
+      eventmachine (>= 0.12.9)
+      http_parser.rb (~> 0)
+    eventmachine (1.2.7)
+    ffi (1.16.3)
+    forwardable-extended (2.6.0)
+    google-protobuf (4.26.1-x86_64-linux)
+      rake (>= 13)
+    http_parser.rb (0.8.0)
+    i18n (1.14.4)
+      concurrent-ruby (~> 1.0)
+    jekyll (4.3.3)
+      addressable (~> 2.4)
+      colorator (~> 1.0)
+      em-websocket (~> 0.5)
+      i18n (~> 1.0)
+      jekyll-sass-converter (>= 2.0, < 4.0)
+      jekyll-watch (~> 2.0)
+      kramdown (~> 2.3, >= 2.3.1)
+      kramdown-parser-gfm (~> 1.0)
+      liquid (~> 4.0)
+      mercenary (>= 0.3.6, < 0.5)
+      pathutil (~> 0.9)
+      rouge (>= 3.0, < 5.0)
+      safe_yaml (~> 1.0)
+      terminal-table (>= 1.8, < 4.0)
+      webrick (~> 1.7)
+    jekyll-include-cache (0.2.1)
+      jekyll (>= 3.7, < 5.0)
+    jekyll-sass-converter (3.0.0)
+      sass-embedded (~> 1.54)
+    jekyll-seo-tag (2.8.0)
+      jekyll (>= 3.8, < 5.0)
+    jekyll-watch (2.2.1)
+      listen (~> 3.0)
+    just-the-docs (0.8.1)
+      jekyll (>= 3.8.5)
+      jekyll-include-cache
+      jekyll-seo-tag (>= 2.0)
+      rake (>= 12.3.1)
+    kramdown (2.4.0)
+      rexml
+    kramdown-parser-gfm (1.1.0)
+      kramdown (~> 2.0)
+    liquid (4.0.4)
+    listen (3.9.0)
+      rb-fsevent (~> 0.10, >= 0.10.3)
+      rb-inotify (~> 0.9, >= 0.9.10)
+    mercenary (0.4.0)
+    pathutil (0.16.2)
+      forwardable-extended (~> 2.6)
+    public_suffix (5.0.5)
+    rake (13.2.1)
+    rb-fsevent (0.11.2)
+    rb-inotify (0.10.1)
+      ffi (~> 1.0)
+    rexml (3.2.6)
+    rouge (4.2.1)
+    safe_yaml (1.0.5)
+    sass-embedded (1.74.1-x86_64-linux-gnu)
+      google-protobuf (>= 3.25, < 5.0)
+    terminal-table (3.0.2)
+      unicode-display_width (>= 1.1.1, < 3)
+    unicode-display_width (2.5.0)
+    webrick (1.8.1)
+
+PLATFORMS
+  x86_64-linux
+
+DEPENDENCIES
+  jekyll (~> 4.3.3)
+  just-the-docs (= 0.8.1)
+
+BUNDLED WITH
+   2.4.22

docs/README.md

@@ -0,0 +1,13 @@
+# ResultWizard documentation
+
+🧾 Find the documentation [here](https://resultwizard.github.io/ResultWizard/).
+
+To build and preview the docs locally, see [this](https://github.com/just-the-docs/just-the-docs-template?tab=readme-ov-file#building-and-previewing-your-site-locally). In summary, have [Bundler](https://bundler.io/) installed, then run:
+
+```bash
+cd docs/
+bundle install
+bundle exec jekyll serve
+```
+
+Preview the docs at [localhost:4000](http://localhost:4000). Files are stored in the `_site` directory locally.

docs/_api/config.md

@@ -0,0 +1,54 @@
+---
+layout: default
+title: wiz.config_init() & wiz.config()
+nav_order: 1
+---
+
+# `wiz.config_init` & `wiz.config()`
+{: .no_toc }
+
+<details markdown="block">
+  <summary>
+    Content
+  </summary>
+  {: .text-delta }
+
+- TOC
+{:toc}
+
+</details>
+
+
+## Purpose
+
+The methods `wiz.config_init()` and `wiz.config()` allow you to configure `ResultWizard` to your needs. Note that this mainly affects the rounding mechanism as well as convenience features. How the results are formatted in the LaTeX document is mainly controlled by the `siunitx` package and how you set it up in your LaTeX preamble. If this is what you want to configure, then you should take a look [here](/tips/siunitx).
+
+## Usage
+
+With `config_init()` you set the initial configuration for `ResultWizard`. With later calls to `config()`, you can update individual settings without having to reconfigure every parameter.
+
+{: .warning }
+Some options are only available in `config_init()` and cannot be changed later with `config()`.
+<br>TODO: Do we really want that?
+
+Here is the list of available options:
+
+{: .warning }
+TODO: sort options alphabetically? Make clearer what the difference between `sigfigs` and `sigfigs_fallback` is. Maybe even rename/unify these options? Same for `decimal_places` and `decimal_places_fallback`. We also need better explanations for `min_exponent_...` and `max_exponent_...`.
+
+| Option | Default | Available in<br>`config_init()` | Available in <br>`config()` | Description |
+|:---|:---:|:---:|:---:|:---|
+| `sigfigs` (int) | `-1` | ✔ | ✔ | The number of significant figures to round to.<br>TODO: explain what a sigfig is. |
+| `decimal_places` (int) | `-1` | ✔ | ✔ | The number of decimal places to round to. |
+| `sigfigs_fallback` (int) | `2` | ✔ | ✔ | The number of significant figures to use as a fallback if other rounding rules don't apply. |
+| `decimal_places_fallback` (int) | `-1` | ✔ | ✔ | The number of decimal places to use as a fallback if other rounding rules don't apply. |
+| `identifier` (str) | `"result"` | ✔ | | The identifier that will be used in the LaTeX document to reference the result. |
+| `print_auto` (bool) | `False` | ✔ | ✔ | If `True`, every call to `wiz.res()` will automatically print the result to the console, such that you don't have to use `.print()` on every single result. |
+| `export_auto_to` (str) | `""` | ✔ |  | If set to a path, every call to `wiz.res()` will automatically export the result to the specified file. This is especially useful for Jupyter notebooks where every execution of a cell that contains a call to `wiz.res()` will automatically export to the file. |
+| `siunitx_fallback` (bool) | `False` | ✔ | | If `True`, `ResultWizard` will use a fallback for the `siunitx` package if you have an old version installed. See [here](/trouble#package-siunitx-invalid-number) for more information. We don't recommend to use this option and instead upgrade your `siunitx` version to exploit the full power of `ResultWizard`. |
+`precision` (int) | `100` | ✔ | | The precision `ResultWizard` uses internally to handle the floating point numbers. You may have to increase this number if you encounter the error "Your precision is set too low". |
+| `ignore_result_overwrite` (bool) | `False` | ✔ | | If `True`, `ResultWizard` will not raise a warning if you overwrite a result with the same identifier. This is especially useful for Jupyter notebooks where cells are oftentimes run multiple times. |
+| `min_exponent_for_`<br>`non_scientific_notation` (int) | `-2` | ✔ | | The minimum exponent for which `ResultWizard` will use non-scientific notation. If the exponent is smaller than this value, scientific notation will be used. TODO: explain better. |
+| `max_exponent_for_`<br>`non_scientific_notation` (int) | `3` | ✔ | | The maximum exponent for which `ResultWizard` will use non-scientific notation. If the exponent is larger than this value, scientific notation will be used. TODO: explain better. |
+
+If you're using a Jupyter Notebook, you might find [this configuration](/tips/jupyter) useful.

docs/_api/export.md

@@ -0,0 +1,39 @@
+---
+layout: default
+title: wiz.export()
+nav_order: 3
+---
+
+# `wiz.export()`
+{: .no_toc }
+
+<details markdown="block">
+  <summary>
+    Content
+  </summary>
+  {: .text-delta }
+
+- TOC
+{:toc}
+
+</details>
+
+
+## Purpose
+
+Call `wiz.export()` after you have defined your results with `wiz.res()`. `wiz.export()` will generate a LaTeX file containing all your results. This file can be included in your LaTeX document with `\input{./path/to/results.tex}` in the LaTeX preamble (see [here](/quickstart#2-include-results-in-latex)).
+
+## Usage
+
+```py
+wiz.export(filepath: str)
+```
+
+- `filepath` (str): The (relative or absolute) path to the LaTeX file to be generated, e.g. `./results.tex`.
+
+
+## Tips
+
+- The `filepath` should end with `.tex` to be recognized as a LaTeX file by your IDE / LaTeX editor.
+- For a convenient setup, have Python code reside next to your LaTeX document. This way, you can easily reference the generated LaTeX file. For example, you could have two folders `latex/` & `code/` in your project. Then export the results to `../latex/results.tex` from your python code residing in the `code` folder. In LaTeX, you can then include the file with `\input{./results.tex}`.
+- Especially for Jupyter Notebooks, we recommend to use the [`export_auto_to` config option](/api/config#export_auto_to). This way, you can automatically export the results to a file after each call to `wiz.res()`. See [this page](/tips/jupyter) for a suitable configuration of `ResultWizard` in Jupyter Notebooks.