Update docs and add doctests

[abhro]

Please see the commmit messages for relevant changes

[github-actions]

Benchmark Results (Julia v1.10)

Time benchmarks

	main	033d428...	main / 033d428...
Quantity/creation/Quantity(x)	3.41 ± 0.01 ns	2.79 ± 0.01 ns	1.22 ± 0.0056
Quantity/creation/Quantity(x, length=y)	3.11 ± 0.01 ns	3.41 ± 0.01 ns	0.912 ± 0.004
Quantity/with_numbers/*real	3.1 ± 0.01 ns	3.1 ± 0.01 ns	1 ± 0.0046
Quantity/with_numbers/^int	8.98 ± 2.5 ns	8.05 ± 2.2 ns	1.11 ± 0.43
Quantity/with_numbers/^int * real	9.6 ± 2.5 ns	8.36 ± 1.9 ns	1.15 ± 0.39
Quantity/with_quantity/+y	4.04 ± 0.001 ns	4.04 ± 0.001 ns	1 ± 0.00035
Quantity/with_quantity//y	3.41 ± 0.01 ns	3.11 ± 0.01 ns	1.1 ± 0.0048
Quantity/with_self/dimension	3.1 ± 0.01 ns	3.1 ± 0.01 ns	1 ± 0.0046
Quantity/with_self/inv	3.11 ± 0.01 ns	3.11 ± 0.001 ns	1 ± 0.0032
Quantity/with_self/ustrip	3.71 ± 0.92 ns	2.79 ± 0.01 ns	1.33 ± 0.33
QuantityArray/broadcasting/multi_array_of_quantities	0.141 ± 0.0026 ms	0.143 ± 0.0018 ms	0.989 ± 0.022
QuantityArray/broadcasting/multi_normal_array	0.062 ± 0.00019 ms	0.0527 ± 0.003 ms	1.18 ± 0.068
QuantityArray/broadcasting/multi_quantity_array	0.155 ± 0.0012 ms	0.157 ± 0.00084 ms	0.992 ± 0.0095
QuantityArray/broadcasting/x^2_array_of_quantities	22.2 ± 1.1 μs	23 ± 1.4 μs	0.967 ± 0.074
QuantityArray/broadcasting/x^2_normal_array	4.17 ± 0.94 μs	4.15 ± 0.65 μs	1 ± 0.28
QuantityArray/broadcasting/x^2_quantity_array	6.9 ± 0.31 μs	6.9 ± 0.31 μs	1 ± 0.064
QuantityArray/broadcasting/x^4_array_of_quantities	0.0843 ± 0.00054 ms	0.0816 ± 0.00056 ms	1.03 ± 0.0097
QuantityArray/broadcasting/x^4_normal_array	0.059 ± 0.00015 ms	0.0498 ± 0.00016 ms	1.19 ± 0.0049
QuantityArray/broadcasting/x^4_quantity_array	0.0591 ± 0.00016 ms	0.0529 ± 0.002 ms	1.12 ± 0.041
time_to_load	0.184 ± 0.00094 s	0.185 ± 0.00078 s	0.996 ± 0.0066

Memory benchmarks

	main	033d428...	main / 033d428...
Quantity/creation/Quantity(x)	0 allocs: 0 B	0 allocs: 0 B
Quantity/creation/Quantity(x, length=y)	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/*real	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/^int	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/^int * real	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_quantity/+y	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_quantity//y	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/dimension	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/inv	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/ustrip	0 allocs: 0 B	0 allocs: 0 B
QuantityArray/broadcasting/multi_array_of_quantities	2 allocs: 0.382 MB	2 allocs: 0.382 MB	1
QuantityArray/broadcasting/multi_normal_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
QuantityArray/broadcasting/multi_quantity_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
QuantityArray/broadcasting/x^2_array_of_quantities	2 allocs: 0.382 MB	2 allocs: 0.382 MB	1
QuantityArray/broadcasting/x^2_normal_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
QuantityArray/broadcasting/x^2_quantity_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
QuantityArray/broadcasting/x^4_array_of_quantities	2 allocs: 0.382 MB	2 allocs: 0.382 MB	1
QuantityArray/broadcasting/x^4_normal_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
QuantityArray/broadcasting/x^4_quantity_array	2 allocs: 0.0763 MB	2 allocs: 0.0763 MB	1
time_to_load	0.153 k allocs: 14.5 kB	0.153 k allocs: 14.5 kB	1

[github-actions]

Benchmark Results (Julia v1)

Time benchmarks

	main	033d428...	main / 033d428...
Quantity/creation/Quantity(x)	3.1 ± 0.01 ns	3.1 ± 0.01 ns	0.997 ± 0.0045
Quantity/creation/Quantity(x, length=y)	3.73 ± 0.01 ns	3.73 ± 0.01 ns	1 ± 0.0038
Quantity/with_numbers/*real	2.79 ± 0.001 ns	2.79 ± 0.001 ns	1 ± 0.00051
Quantity/with_numbers/^int	8.67 ± 2.2 ns	8.67 ± 2.2 ns	1 ± 0.35
Quantity/with_numbers/^int * real	9.29 ± 2.2 ns	18.2 ± 0.98 ns	0.51 ± 0.12
Quantity/with_quantity/+y	4.35 ± 0.009 ns	4.35 ± 0.001 ns	1 ± 0.0021
Quantity/with_quantity//y	3.42 ± 0.011 ns	3.42 ± 0.011 ns	1 ± 0.0046
Quantity/with_self/dimension	3.1 ± 0.01 ns	3.1 ± 0.01 ns	1 ± 0.0046
Quantity/with_self/inv	3.11 ± 0.001 ns	3.11 ± 0.001 ns	1 ± 0.00046
Quantity/with_self/ustrip	3.1 ± 0.01 ns	3.1 ± 0.01 ns	1 ± 0.0046
QuantityArray/broadcasting/multi_array_of_quantities	0.0904 ± 0.00031 ms	0.0907 ± 0.00077 ms	0.996 ± 0.0091
QuantityArray/broadcasting/multi_normal_array	0.0498 ± 0.00019 ms	0.0498 ± 0.00026 ms	0.999 ± 0.0065
QuantityArray/broadcasting/multi_quantity_array	0.0622 ± 0.0086 ms	0.0532 ± 0.0092 ms	1.17 ± 0.26
QuantityArray/broadcasting/x^2_array_of_quantities	13.1 ± 1.8 μs	13.3 ± 1.2 μs	0.989 ± 0.16
QuantityArray/broadcasting/x^2_normal_array	1.99 ± 1.7 μs	2.06 ± 1.4 μs	0.966 ± 1
QuantityArray/broadcasting/x^2_quantity_array	3.51 ± 0.25 μs	3.47 ± 0.12 μs	1.01 ± 0.081
QuantityArray/broadcasting/x^4_array_of_quantities	0.0842 ± 0.0012 ms	0.0846 ± 0.00055 ms	0.996 ± 0.016
QuantityArray/broadcasting/x^4_normal_array	0.0497 ± 0.00012 ms	0.0497 ± 0.00016 ms	1 ± 0.004
QuantityArray/broadcasting/x^4_quantity_array	0.0468 ± 0.00015 ms	0.0498 ± 0.00018 ms	0.938 ± 0.0045
time_to_load	0.2 ± 0.0047 s	0.199 ± 0.0024 s	1 ± 0.026

Memory benchmarks

	main	033d428...	main / 033d428...
Quantity/creation/Quantity(x)	0 allocs: 0 B	0 allocs: 0 B
Quantity/creation/Quantity(x, length=y)	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/*real	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/^int	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_numbers/^int * real	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_quantity/+y	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_quantity//y	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/dimension	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/inv	0 allocs: 0 B	0 allocs: 0 B
Quantity/with_self/ustrip	0 allocs: 0 B	0 allocs: 0 B
QuantityArray/broadcasting/multi_array_of_quantities	3 allocs: 0.382 MB	3 allocs: 0.382 MB	1
QuantityArray/broadcasting/multi_normal_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
QuantityArray/broadcasting/multi_quantity_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
QuantityArray/broadcasting/x^2_array_of_quantities	3 allocs: 0.382 MB	3 allocs: 0.382 MB	1
QuantityArray/broadcasting/x^2_normal_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
QuantityArray/broadcasting/x^2_quantity_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
QuantityArray/broadcasting/x^4_array_of_quantities	3 allocs: 0.382 MB	3 allocs: 0.382 MB	1
QuantityArray/broadcasting/x^4_normal_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
QuantityArray/broadcasting/x^4_quantity_array	3 allocs: 0.0764 MB	3 allocs: 0.0764 MB	1
time_to_load	0.159 k allocs: 11.2 kB	0.159 k allocs: 11.2 kB	1

[icweaver]

Hi @abhro, hope you've been well! I love this PR and just wanted to check back in about its current status. I think getting it in would be really helpful for keeping the docs in sync with the QuantityArray PR (#178) I'm working on, especially if we could make the use of @example blocks a bit more ubiquitous here

[abhro]

Hi! I think I've addressed all the changes, it's most likely just the CI checks now

[icweaver]

Oh, could we also add the generated index.md file to .gitignore? I accidentally uploaded it in another PR, haha. And probably /test/Manifest.toml for completeness too?

[abhro]

Done!

[icweaver]

Sweet, thanks!

Have you been able to generate docs with the Mirror to DAMTP bit btw? I've been finding that since it it relies on an ENV in CI, it fails when I try to build locally, so I've just been commenting it our for now. I'm wondering if it would make sense to hide that bit behind a conditional flag that's called during CI?

[abhro]

Have you been able to generate docs with the Mirror to DAMTP bit btw? I've been finding that since it it relies on an ENV in CI, it fails when I try to build locally, so I've just been commenting it our for now. I'm wondering if it would make sense to hide that bit behind a conditional flag that's called during CI?

I'm guessing this part is meant for @MilesCranmer? I'm not sure I can offer much help on the deployment side of things

[icweaver]

Sorry, I should have said "because of the Mirror to DAMTP bit" instead of "with the Mirror to DAMTP bit". In other words, this seems like an issue for anyone trying to build the docs locally, so I just wanted to see if we could smooth that process out a bit for folks.

Similarly, I was wondering if it might also be good to add a tip about using LiveServer.jl with something like:

servedocs(; include_dirs=["src/"], skip_files=["docs/src/index.md"])

so things work well from the jump. Anyway, just wanted to get your perspective to get an idea of if something like this would be helpful or not, haha

[abhro]

Sorry, I should have said "because of the Mirror to DAMTP bit" instead of "with the Mirror to DAMTP bit". In other words, this seems like an issue for anyone trying to build the docs locally, so I just wanted to see if we could smooth that process out a bit for folks.

Mmm, yes, that's probably a good idea to add a guard to check if the build is happening in CI or not.