# How to group several modules in a package

**URL:** <https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627>\
**Category:** New to Julia\
**Tags:** packages, book, tutorials\
**Created:** [September 6, 2018, 3:46pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627 "2018-09-06T15:46:09Z")\
**Posts on this page:** 8\
**Page:** 2

<div class="post-metadata">

**Author:** ![tobias.knopp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tobias.knopp/32/7551_2.png) [@tobias.knopp](https://discourse.julialang.org/u/tobias.knopp)\
**Post date:** [September 7, 2018, 12:06pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/21 "2018-09-07T12:06:40Z")

</div>

Wait. What you are looking for are Doctests, right? These are available in Documenter.jl:

[https://juliadocs.github.io/Documenter.jl/stable/man/doctests/#Doctests-1](https://juliadocs.github.io/Documenter.jl/stable/man/doctests/#Doctests-1)

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 12:09pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/22 "2018-09-07T12:09:33Z")

</div>

I think there’s a misunderstanding here - I’m not against having examples in the documentation for the user to run themselves; What I’m saying is that those examples for the user are a different thing to “automatically running tests on a package”, which is what CI is for. Those examples are used as an introduction to a user, while actual unit tests are for testing whether the package itself works as intended by the author and does what it’s supposed to do.

In regards to running those examples automatically - I’m not quite sure what you mean here. Are you thinking about running those examples and showing the user the output?

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 12:14pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/23 "2018-09-07T12:14:36Z")

</div>

Thank you, that’s a useful answer!

However, `Documenter.jl` says to use `jldoctest` while the Julia docs says to use `julia-repl` for examples. So I am still a bit confused about what to do.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 12:17pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/24 "2018-09-07T12:17:32Z")

</div>

I am just saying that in a first approach having as CI tests running the examples in the doc is better to have no tests at all. I have been maintaining huge packages in GAP3 with only such tests, and with a good enough documentation this is very useful. Most Julia docs I have looked at are in contrast very terse and contain few if any examples so they are not suitable.

---

<div class="post-metadata">

**Author:** ![Sukera](https://avatars.discourse-cdn.com/v4/letter/s/ce7236/32.png) [@Sukera](https://discourse.julialang.org/u/Sukera)\
**Post date:** [September 7, 2018, 12:33pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/25 "2018-09-07T12:33:28Z")

</div>

I’m not familiar with GAP3, are you talking about something like [this](https://webusers.imj-prg.fr/~jean.michel/gap3/manual.pdf)?

Ah, I understand now. Yes, that indeed is what Documenter can do. Having those running is better than no tests at all, but they’re certainly not the only thing that should be run when `test`ing a package (in the software development sense, not in the sense of trying a package out to see if it’s a good fit). If you’re just “shopping around” for packages, a good introduction to that package is of course necessary - but again, that’s a different thing to automatically testing whether the package works as intended.

In any case (and I’m aware that this is a very subjective topic and that this is just an opinion), I don’t think just running examples from documentation is providing good enough test coverage for the actual code and functionality. Not every possible combination of arguments for a function can or should be presented in documentation, and often there are absurd weird combinations that trigger a bug - fixing those and writing a unit test to detect if that bug shows up again in the future is very much a necessity, but shouldn’t necessarily be documented in reference manuals. Especially invalid input and error states are things to be tested in unit tests, to ensure proper function of the code while not really suitable for documentation.

* * *

The bare minimum for a julia package is still just basic git version control. Neither CI nor documentation is technically required. But it’s very much recommended to ensure much easier maintainability and usability of a package.

---

<div class="post-metadata">

**Author:** ![Jean\_Michel](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/jean_michel/32/8282_2.png) [@Jean\_Michel](https://discourse.julialang.org/u/Jean_Michel)\
**Post date:** [September 7, 2018, 12:37pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/26 "2018-09-07T12:37:05Z")

</div>

> [@Sukera](#):
>
> are you talking about something like [this](https://webusers.imj-prg.fr/~jean.michel/gap3/manual.pdf)?

Yes

And of course additional tests may be needed than the documentation, but the documentation may contain  
90% of the necessary tests which thus don’t have to be written twice.

---

<div class="post-metadata">

**Author:** ![tobias.knopp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tobias.knopp/32/7551_2.png) [@tobias.knopp](https://discourse.julialang.org/u/tobias.knopp)\
**Post date:** [September 7, 2018, 1:02pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/27 "2018-09-07T13:02:46Z")

</div>

> [@Jean\_Michel](#):
>
> However, `Documenter.jl` says to use `jldoctest` while the Julia docs says to use `julia-repl` for examples. So I am still a bit confused about what to do.

Documenter.jl is an additional package so its clear that the julia documentation will not mention it. I have no experience in running the doctest but Documenter is usually on travis after the regular test. I am right now not sure if they influence the CI result (pass/fail).

---

<div class="post-metadata">

**Author:** ![Tamas\_Papp](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/tamas_papp/32/25949_2.png) [@Tamas\_Papp](https://discourse.julialang.org/u/Tamas_Papp)\
**Post date:** [September 7, 2018, 1:50pm UTC](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627/28 "2018-09-07T13:50:41Z")

</div>

> [@tobias.knopp](#):
>
> I am right now not sure if they influence the CI result (pass/fail).

Depends on your script/setup. You can run do it either way.

[Previous page](https://discourse.julialang.org/t/how-to-group-several-modules-in-a-package/14627.md?page=1)