I’m trying to understand how examples in the documentation work.
I’m very familiar with R and there we can include other libraries that are not specifically needed for package functionality in the “Suggests” field of the DESCRIPTION file since the package will work without this dependency, it’s only required for examples.
I’m trying to write clear examples that require importing a CSV file of weather data to run a model with said data. I’m happy to use DelimitedFiles.jl in place of CSV.jl to reduce the compilation time, but I’m unclear as to whether it is acceptable to use a stdlib module since internally the package doesn’t use it. It’s just for importing data for example purposes. Else, do you just write dummy examples that don’t work and have more detailed examples in the docs folder in that environment with its own dependency handling.
I don’t see anything wrong with using extra packages in documentation/examples that aren’t used by the package internally. After all, the documentation has its own environment and dependency list. It’s always better to use examples that work, and I like to use Literate.jl for this. As an example, have a look at Solving PDEs · ApproxFun.jl, where I use Plots.jl to visualize solutions to differential equations, but Plots is not a dependency of ApproxFun.
Yes, that’s exactly what I was pointing to use in the docs environment. Perhaps I wasn’t clear. I’m trying to understand the docstrings themselves.
The model won’t run without data, so I can’t really write a functional example without importing data in the docstring example. In the documents, I can go wild and use whatever since it’s a different environment, but in the docstrings for the functions, can I do this? Use other packages to demonstrate how to use the package that aren’t necessary for the functionality within the package itself? I guess my lack of clarity comes from this documentation, Documentation · The Julia Language where it says,
Werever possible examples should be self-contained and runnable so that readers are able to try them out without having to include any dependencies.
I suppose maybe this is one of those where it’s not possible so it’s permissible.