From 62c34a571fa8250e0a09027c9f548be19a3a7186 Mon Sep 17 00:00:00 2001 From: Splines <37160523+Splines@users.noreply.github.com> Date: Sat, 27 Apr 2024 19:45:34 +0200 Subject: [PATCH] Add missing `site.baseurl` to relative links (#52) --- docs/_api/config.md | 6 +++--- docs/_api/export.md | 4 ++-- docs/_api/res.md | 8 ++++---- docs/_tips/jupyter.md | 2 +- docs/_tips/siunitx.md | 2 +- docs/index.md | 2 +- docs/pages/quickstart.md | 6 +++--- docs/pages/trouble.md | 4 ++-- 8 files changed, 17 insertions(+), 17 deletions(-) diff --git a/docs/_api/config.md b/docs/_api/config.md index efd37cc..cdadfbb 100644 --- a/docs/_api/config.md +++ b/docs/_api/config.md @@ -21,7 +21,7 @@ nav_order: 1 ## 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). +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]({{site.baseurl}}/tips/siunitx). ## Usage @@ -45,10 +45,10 @@ TODO: sort options alphabetically? Make clearer what the difference between `sig | `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`. | +| `siunitx_fallback` (bool) | `False` | ✔ | | If `True`, `ResultWizard` will use a fallback for the `siunitx` package if you have an old version installed. See [here]({{site.baseurl}}/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_`
`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_`
`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. +If you're using a Jupyter Notebook, you might find [this configuration]({{site.baseurl}}/tips/jupyter) useful. diff --git a/docs/_api/export.md b/docs/_api/export.md index 6d8eabb..a476f08 100644 --- a/docs/_api/export.md +++ b/docs/_api/export.md @@ -21,7 +21,7 @@ nav_order: 3 ## 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)). +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]({{site.baseurl}}/quickstart#2-include-results-in-latex)). ## Usage @@ -36,4 +36,4 @@ wiz.export(filepath: str) - 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. +- Especially for Jupyter Notebooks, we recommend to use the [`export_auto_to` config option]({{site.baseurl}}/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]({{site.baseurl}}/tips/jupyter) for a suitable configuration of `ResultWizard` in Jupyter Notebooks. diff --git a/docs/_api/res.md b/docs/_api/res.md index 6836822..0f68937 100644 --- a/docs/_api/res.md +++ b/docs/_api/res.md @@ -24,7 +24,7 @@ The API for `wiz.res()` is not yet finalized as of `v1.0.0a2` and might change b ## Purpose -`wiz.res()` is at the heart of `ResultWizard`. With this method, you define your results, i.e. numerical values with uncertaintie(s) (optional) and a unit (optional). See the [basic usage](/quickstart#-basic-usage) for a first example. +`wiz.res()` is at the heart of `ResultWizard`. With this method, you define your results, i.e. numerical values with uncertaintie(s) (optional) and a unit (optional). See the [basic usage]({{site.baseurl}}/quickstart#-basic-usage) for a first example. When we talk about a **"measurement result"**, we usually refer to these components: @@ -80,7 +80,7 @@ wiz.res("abc", "1.2345", str(calculated_uncert)).print() # will print: abc = 1.2345 ± 0.063 ``` -You might also use the following keyword arguments with any signature of `wiz.res()`. They will override whatever you have configured via [`config_init()` or `config()`](/api/config), but just for the specific result. +You might also use the following keyword arguments with any signature of `wiz.res()`. They will override whatever you have configured via [`config_init()` or `config()`]({{site.baseurl}}/api/config), but just for the specific result. ```py wiz.res(name, ..., sigfigs: int = None, decimal_places: int = None) ``` @@ -97,7 +97,7 @@ my_latex_str = my_res.to_latex_str() print(my_latex_str) # will print: \num{1.23 \pm 0.06} ``` -- `print()` will print the result to the console. If you find yourself using this a lot, consider setting the [`print_auto` config option](/api/config#print_auto) to `True`, which will automatically print the result after each call to `wiz.res()`. +- `print()` will print the result to the console. If you find yourself using this a lot, consider setting the [`print_auto` config option]({{site.baseurl}}/api/config#print_auto) to `True`, which will automatically print the result after each call to `wiz.res()`. - `to_latex_str()` converts the result to a LaTeX string. This might be useful if you want to show the result as label in a `matplotlib` plot. For this to work, you have to tell `matplotlib` that you're using `siunitx` by defining the preamble in your Python script: ```py import matplotlib.pyplot as plt @@ -112,7 +112,7 @@ plt.rc('text.latex', preamble=r""" ## Tips You might need a variable in your LaTeX document multiple times: in one place _with_ a unit and in another one _without_ a unit (or uncertainty etc.). Don't define the result twice in this case. -Instead, call `wiz.res()` once and pass in everything you know about your result, e.g. value, unit, uncertainties. Then use `$$\resultMyVariableName[withoutUnit]$$` or `$$\resultMyVariableName[unit]$$` etc. in the LaTeX document to only use a specific part of the result. See the [quickstart](/quickstart#latex-subset-syntax) for more information. +Instead, call `wiz.res()` once and pass in everything you know about your result, e.g. value, unit, uncertainties. Then use `$$\resultMyVariableName[withoutUnit]$$` or `$$\resultMyVariableName[unit]$$` etc. in the LaTeX document to only use a specific part of the result. See the [quickstart]({{site.baseurl}}/quickstart#latex-subset-syntax) for more information. --- diff --git a/docs/_tips/jupyter.md b/docs/_tips/jupyter.md index e7eb95a..110d8f1 100644 --- a/docs/_tips/jupyter.md +++ b/docs/_tips/jupyter.md @@ -35,7 +35,7 @@ wiz.config_init(print_auto=True, export_auto_to="./results.tex", ignore_result_o ## Cell execution order & cache -Watch out if you use [`wiz.config()`](/api/config) in a Jupyter Notebook. The order of the cell execution is what matters, not where they appear in the document. E.g. you might call `wiz.config()` somewhere at the end of your notebook. Then go back to the top and execute a cell with `wiz.res()`. The configuration will be applied to this cell as well. This is an inherent limitation/feature of Jupyter Notebooks, just be aware of it. +Watch out if you use [`wiz.config()`]({{site.baseurl}}/api/config) in a Jupyter Notebook. The order of the cell execution is what matters, not where they appear in the document. E.g. you might call `wiz.config()` somewhere at the end of your notebook. Then go back to the top and execute a cell with `wiz.res()`. The configuration will be applied to this cell as well. This is an inherent limitation/feature of Jupyter Notebooks, just be aware of it. It might be useful to reset the kernel and clear all outputs from time to time. This way, you can also check if your notebook still runs as expected from top to bottom and exports the results correctly. It can also help get rid of any clutter in `results.tex`, e.g. if you have exported a variable that you deleted later on in the code. This variable will still be in `results.tex` as deleting the `wiz.res()` line in the code doesn't remove the variable from the cache. diff --git a/docs/_tips/siunitx.md b/docs/_tips/siunitx.md index 85dc9b6..7f25663 100644 --- a/docs/_tips/siunitx.md +++ b/docs/_tips/siunitx.md @@ -23,7 +23,7 @@ nav_order: 2 The [`siunitx`] package offers a wide range of options to configure the formatting of numbers and units in LaTeX. In the exported `results.tex` file, we make use of `siunitx` syntax, e.g. we might transform a `wiz.res()` call into something like `\qty{1.23 \pm 0.05}{\m\per\s^2}` that you also could have written manually. This means, you have full control over how the numbers and units are displayed in your LaTeX document by configuring `siunitx` itself. -If you want to configure `ResultWizard` itself instead, see the [`config_init()` & `config()`](/api/config) methods. +If you want to configure `ResultWizard` itself instead, see the [`config_init()` & `config()`]({{site.baseurl}}/api/config) methods. ## Important configuration options diff --git a/docs/index.md b/docs/index.md index 82b3db8..da53d17 100644 --- a/docs/index.md +++ b/docs/index.md @@ -16,7 +16,7 @@ between Python code & your LaTeX work. {: .fs-6 .fw-300 } -{% capture intro_link %}{{ site.baseurl }}{% link pages/quickstart.md %}{% endcapture %} +{% capture intro_link %}{% link pages/quickstart.md %}{% endcapture %} [Quickstart]({{intro_link}}){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 } [Source Code (GitHub)](https://github.com/resultwizard/ResultWizard){: .btn .fs-5 .mb-4 .mb-md-0 } [PyPI](https://pypi.org/project/resultwizard/){: .btn .fs-5 .mb-4 .mb-md-0 } diff --git a/docs/pages/quickstart.md b/docs/pages/quickstart.md index f11e909..3dde477 100644 --- a/docs/pages/quickstart.md +++ b/docs/pages/quickstart.md @@ -28,9 +28,9 @@ nav_order: 2 - It's not primarily for you, if you're writing your LaTeX code in a web-based editor like Overleaf. `ResultWizard` is a Python package that will export a `.tex` file in the end. You have to include this file in your LaTeX project and the closer your Python code is to your LaTeX document, the easier it is to reference it without having to do anything manually in-between. You could still use `ResultWizard` in your Python code and manually copy the contents of the generated `results.tex` file into Overleaf, but this is not the originally intended workflow. - The same philosophy applies to Jupyter Notebooks that run in a browser. Instead, you should use a local Jupyter Notebook setup and have your LaTeX project reside next to your Python code. Using VSCode as editor is one way to do this. It has built-in support [for Jupyter Notebooks](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) and with the [LaTeX Workshop extension](https://marketplace.visualstudio.com/items?itemName=James-Yu.latex-workshop) you can easily compile your LaTeX document and see the changes immediately. For a possible setup within WSL, see [this guide](https://github.com/Splines/vscode-latex-wsl-setup). -Ideally, you'd have a folder structure where `code` (or `python` or `src` or whatever) and `thesis` (or `latex` or `document` or whatever) are folders on the same level. See also the [wiz.export() API](/api/export). +Ideally, you'd have a folder structure where `code` (or `python` or `src` or whatever) and `thesis` (or `latex` or `document` or whatever) are folders on the same level. See also the [wiz.export() API]({{site.baseurl}}/api/export). -Ideally, you also have used the [`siunitx`] LaTeX package beforehand to know how to format units, e.g. `\m\per\s^2`. But don't worry if you haven't, you can still use `ResultWizard` and learn about `siunitx` along the way. You might also want to check out the [siunitx configuration](/tips/siunitx) page. +Ideally, you also have used the [`siunitx`] LaTeX package beforehand to know how to format units, e.g. `\m\per\s^2`. But don't worry if you haven't, you can still use `ResultWizard` and learn about `siunitx` along the way. You might also want to check out the [siunitx configuration]({{site.baseurl}}/tips/siunitx) page. @@ -142,7 +142,7 @@ wiz.config_init(sigfigs_fallback=3, identifier="customResult") # default to 2 and "result" respectively ``` -If you're working in a *Jupyter Notebook*, please see [this page](tips/jupyter) for a suitable configuration of `ResultWizard` that doesn't annoy you with warnings and prints/exports the results automatically. +If you're working in a *Jupyter Notebook*, please see [this page]({{site.baseurl}}/tips/jupyter) for a suitable configuration of `ResultWizard` that doesn't annoy you with warnings and prints/exports the results automatically. ### 2. Include results in LaTeX diff --git a/docs/pages/trouble.md b/docs/pages/trouble.md index 497d8a4..ff1951d 100644 --- a/docs/pages/trouble.md +++ b/docs/pages/trouble.md @@ -19,14 +19,14 @@ nav_order: 3 -There might be several reasons for your LaTeX document not building. **Try to find the root cause** 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 [exported](/api/export) `results.tex` file to see if your editor/IDE shows any errors there. You might encounter one of the following problems. Please make sure to try the solutions provided here before opening an [issue on GitHub](https://github.com/resultwizard/ResultWizard/issues). +There might be several reasons for your LaTeX document not building. **Try to find the root cause** 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 [exported]({{site.baseurl}}/api/export) `results.tex` file to see if your editor/IDE shows any errors there. You might encounter one of the following problems. Please make sure to try the solutions provided here before opening an [issue on GitHub](https://github.com/resultwizard/ResultWizard/issues). ## Package siunitx: Invalid number {: .tldr} -You have probably specified **multiple uncertainties** in `wiz.res()`, right? If this is the case and you get this error, you have an **old version of `siunitx`** installed. Please update it (recommended) or use the `siunitx_fallback` option in the [`config_init`](/api/config) method. +You have probably specified **multiple uncertainties** in `wiz.res()`, right? If this is the case and you get this error, you have an **old version of `siunitx`** installed. Please update it (recommended) or use the `siunitx_fallback` option in the [`config_init`]({{site.baseurl}}/api/config) 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 input". We make use of this feature in `ResultWizard` when you specify multiple uncertainties for a result.