Have a REQUIRE file for the doctests

[davidanthoff]

I think this depends a bit on whether #198 is implemented, but as long as doctests don't only run as part of the normal test suite, it would be good to be able to specify a REQUIRE file for the doctests, like one can specify a REQUIRE file in the test folder for additional packages that are needed for the test runs.

On the other hand, if the model here is changed so that doctests always (and only) run in the context of the normal test suite, this would not be required, because one could just use the REQUIRE file in the test folder.

[MichaelHatherly]

Good idea, though I think this should probably be part of Base.Pkg since it would be good to be able to specify in a docs/REQUIRES as something like

Documenter
# other deps...

so that we can stop having to install Documenter manually in the .travis.yml file, and then just do Pkg.docs("MyPackage") to install all deps, run the make.jl file and then uninstall deps similar to what Pkg.test("MyPackage") does.

Pkg.docs call could even just be part of the default travis script like Pkg.test is now.

Note that for now you can call your docs/make.jl script from the test/runtests.jl script to get the right deps installed. This is what Documenter itself does.

[davidanthoff]

Yes, that sounds great, especially support from Base and tighter integration with travis!

I guess there is a question which requirements should go into docs/REQUIRE and which into test/REQUIRE. I think my preffered solution would actually be that the doctests only run as part of the normal package tests, and that the docs/make.jl file only builds the docs, but doesn't run the doctests. In that case the REQUIRE situation would be clean: docs/REQUIRE has everything needed to build the docs, but not stuff that is needed in the doctests, whereas test/REQUIRE has everything needed by the doctests.

[MichaelHatherly]

I think the line between the two are probably always going to be a bit fuzzy. As far as I'm concerned doctests could easily fit in either test or docs, so supporting either option and letting users decide might be the best route. Currently we have the doctest = false keyword for makedocs, we just need a Documenter.doctest function that does as little as possible just to be able to run the doctests.

[tlnagy]

Would it be possible to have a REQUIRE for packages necessary to create the documentation, but the package otherwise doesn't depend on? See https://github.com/GiovineItalia/Gadfly.jl/blob/master/docs/REQUIRE and https://github.com/GiovineItalia/Gadfly.jl/blob/master/.travis.yml for my workaround. Kind of hacky.

[mortenpi]

Closing this as we now have Project.toml files. The recommendation is that you have a docs/Project.toml file with doc-related dependencies. More information in the docs.