From a8379e8602fc0e87e5a3db35932318d505a5bd5e Mon Sep 17 00:00:00 2001 From: tingerrr Date: Tue, 23 Jan 2024 15:36:42 +0100 Subject: [PATCH] Chore: updated README.md --- README.md | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 1763a63..dc70b8b 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,7 @@ Hydra is a [typst] package allowing you to easily display the heading like eleme document. In short, it will show you the currently active element only when it is not visible. Some of hydra's features rely on the size of the top-margin, if you use a different page size than -`a4` or a custom top margin for your pages, make sure to configure hydra, otherwise those cheks may +`a4` or a custom top margin for your pages, make sure to configure hydra, otherwise those checks may not work. ## Example @@ -38,21 +38,30 @@ not work. For a more in-depth description of hydra's functionality and the reference read its [manual]. ## Contribution +### Bug fixes +If you want to fix an issue please leave a comment there so others know. If you want to fix a bug +which doesn't have an issue yet, please create an issue first. Exceptions are typos or minor +improvements, just making the PR will be enough. + +### Features +When adding features, make sure you add regression tests for this feature. See the testing section +below on testing. Make sure to document the feature, see the manual section on manual and examples +below. + ### Testing -This package serves as my real-world test for [`typst-test`][typst-test], it is not required for -contributions, but encouraged as it speeds up the review process. +To ensure that your changes don't break exisiting code test it using the package's regression tests. +This is done automatically on pull requests, so you don't need not install [typst-test], but it's +nontheless recommended for faster iteration. In general, running `typst-test run` will be enough to +ensure your changes are correct. -Other than that tests can be run using the following command structure for each test: -```bsh -test=... -typst --root . "tests/typ/${test}.typ" "tests/out/${test}/{n}.png" -# some command to compare images in tests/ref/${test} and tests/out/${test} -``` +### Manual and examples +The manual and example images are created from a quite frankly convoluted nushell script. If you +have, or don't mind installing, [nushell], [just] and [imagemagick], then you can simply run `just +gen` to generate a new manual and examples. -## Examples and manual -Furthermore, I use [`just`][just] and [`nushell`][nushell] to run common commands. It's once again -not required, as I'll generate those myself if you don't on a PR, but if you already use both you -can run the example and manual generation using `just gen`. +The examples inside the docs currently don't make it easy to simplify this without generating them +manually the whole time. Typst is missing a feature or plugin that allows embedding whole other +typst documents at the moment. [ex1]: examples/example1.png [ex2]: examples/example2.png @@ -65,3 +74,4 @@ can run the example and manual generation using `just gen`. [typst-test]: https://github.com/tingerrr/typst-test [just]: https://just.systems/ [nushell]: https://www.nushell.sh/ +[imagemagick]: https://imagemagick.org/