I am progressively creating a new package, and have managed to successfully deal with CI and tests. Now I would like to set up a documentation.
I have docstrings for my functions, have created a docs repo with a make.jl file and have activated the github page for this repo.
However, I am stuck at the SSH Deploy Keys part of the documentation. When I run Travis.genkeys("Psycho"), I get an error saying:
julia> Travis.genkeys("Psycho")
WARNING: importing deprecated binding Base.base64encode into Travis.
WARNING: Base.base64encode is deprecated: it has been moved to the standard library package `Base64`.
Add `using Base64` to your imports.
in module Travis
WARNING: Base.base64encode is deprecated: it has been moved to the standard library package `Base64`.
Add `using Base64` to your imports.
in module Travis
WARNING: Base.base64encode is deprecated: it has been moved to the standard library package `Base64`.
Add `using Base64` to your imports.
in module Travis
ERROR: IOError: could not spawn `which which`: no such file or directory (ENOENT)
Stacktrace:
[1] _jl_spawn(::String, ::Array{String,1}, ::Cmd, ::Tuple{Base.DevNullStream,Base.DevNullStream,Base.DevNullStream}) at .\process.jl:370
[2] (::getfield(Base, Symbol("##499#500")){Cmd})(::Tuple{Base.DevNullStream,Base.DevNullStream,Base.DevNullStream}) at .\process.jl:512
[3] setup_stdio(::getfield(Base, Symbol("##499#500")){Cmd}, ::Tuple{Base.DevNullStream,Base.DevNullStream,Base.DevNullStream}) at .\process.jl:493
[4] #_spawn#498(::Nothing, ::Function, ::Cmd, ::Tuple{Base.DevNullStream,Base.DevNullStream,Base.DevNullStream}) at .\process.jl:511
[5] #_spawn at .\none:0 [inlined]
[6] #_spawn#504 at .\process.jl:551 [inlined]
[7] _spawn at .\process.jl:551 [inlined]
[8] success(::Cmd) at .\process.jl:708
[9] #genkeys#1(::String, ::Function, ::String) at C:\Users\Dom\.julia\packages\DocumenterTools\yth8s\src\Travis.jl:46
[10] genkeys(::String) at C:\Users\Dom\.julia\packages\DocumenterTools\yth8s\src\Travis.jl:46
[11] top-level scope at none:0
I also added the - julia -e 'Pkg.add("Documenter"); cd(Pkg.dir("Psycho")); include(joinpath("docs", "make.jl"))' to the travis.yml file but the documentation page remains desperately empty… Any advice?
This looks like the genkeys-does-not-work-on-Windows issue (JuliaDocs/Documenter.jl#761). Documenter v0.19.6 will probably not work either. You have two options (other than running genkeys on linux/mac):
Yesterday I tried installing this famous “which” by installing git, ruby and travis but I didn’t succeed to go further. Anyway, this morning I tried @mortenpi’s workaround.
It got me two files (do I need them somewhere?), a short key that I copied to github settings and a long key that I copied to travis. However, the short key ended with dom@DOM-PC (the name of my computer), but I didn’t paste this part to github. Should I?
Finally, I triggered the build again. This created a gh-pages branch. Unfortunately, the website’s still 404 and the travis build says, at the end:
Network availability confirmed.
Fix WWDRCA Certificate
Unable to delete certificate matching "somesortofcode"
No output has been received in the last 10m0s, this potentially indicates a stalled build or something wrong with the build itself.
Check the details on how to adjust your build configuration on: https://docs.travis-ci.com/user/common-build-problems/#Build-times-out-because-no-output-was-received
The build has been terminated
Any suggestions?
Also, Documenter’s docs suggests to have an mkdocs.yml file, but several packages with a documentation appparently don’t have one. Why?
It will (usually) deploy to the latest/ subdirectory. Did you only try to access the top level directory perhaps? In any case, you can directly look at the gh-pages branch and see exactly what is going on.
It got me two files (do I need them somewhere?)
No. Rather, you should delete them to make sure you don’t expose them accidentally. If you should ever lose one of them from either Travis or GitHub, you can always just easily generate a new set of keys.
However, the short key ended with dom@DOM-PC (the name of my computer), but I didn’t paste this part to github. Should I?
As GitHub appears to accept it without it, it should not matter.
Also, Documenter’s docs suggests to have an mkdocs.yml file, but several packages with a documentation appparently don’t have one. Why?
Documenter has two modes – it can build a set of HTML pages on its own (format = :html), or generate Markdown pages that are then built with MkDocs (format = :markdown or leaving the argument unspecified). While the native HTML option is the preferred one, the docs are a bit outdated in this regard and still explain how to set up the MkDocs version.
What do you mean by that? The gh-pages looks… not empty?
On the second try, the previous message disappeared. Every build is successful. I’ve also changed the github pages source to be connected to the gh-pages branch.
The docs appear to be building, but it looks like it does not complete.
┌ Warning: `Pkg.dir(pkgname, paths...)` is deprecated; instead, do `import Psycho; joinpath(dirname(pathof(Psycho)), "..", paths...)`.
â”” @ Pkg.API /Users/osx/buildbot/slave/package_osx64/build/usr/share/julia/stdlib/v1.0/Pkg/src/API.jl:454
Documenter: setting up build directory.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
> checking for missing docstrings.
!! 2 docstrings potentially missing:
Psycho.f :: Tuple{Number}
Psycho.dupa :: Tuple{Number}
> running doctests.
> checking footnote links.
Documenter: populating indices.
Documenter: rendering document.
Documenter: skipping docs deployment.
You can set DOCUMENTER_DEBUG to "true" in Travis to see more information.
Done. Your build exited with 0.
And the github page is still empty. Thanks for helping me so far!
Also, you have configured your build to deploy on the julia: nightly builds, so you need to look at the output from those Travis runs. I would recommend setting julia = "1.0" in deploydocs though, to make sure you are deploying from a stable Julia version.
If your time allows, please consider updating the docs to suggest HTML (I imagine the change would be minor, as you would just change the suggestion on which to use). IMO pretty much everyone is using the HTML option these days, the mkdocs way could even go to an appendix.
I now have a dev branch ahead of the master, but the docs only generate “latest”. Where can I tell it to generate a stable and latest documentation?
You make a new release (or a tag rather). But if you are still developing the package I would recommend to just use latest, and when you are ready to make a release it will automatically create stable for you.
