Documenter.jl: Version conflict with MkDocs on Travis

[Datseris]

Hello. I am sorry if this is the wrong place to ask this (which probably is) but I couldn't solve looking anywhere else.

My documentation doesn't build on Travis any more. I am using Documenter.jl with MkDocs.

The Travis fail message is:

Documenter: setting up target directory.
Documenter: running extra build steps.
Traceback (most recent call last):
File "/home/travis/.local/bin/mkdocs", line 11, in <module>
sys.exit(cli())
File "/home/travis/.local/lib/python2.7/site-packages/click/core.py", line 722, in __call__
return self.main(*args, **kwargs)
....
...
...
pkg_resources.VersionConflict: (mkdocs 0.17.0 (/home/travis/.local/lib/python2.7/site-packages), Requirement.parse('mkdocs==0.16.3'))

ERROR: LoadError: failed process: Process(`mkdocs build`, ProcessExited(1)) [1]

Because the stacktrace is too long, I am posting a link to the build: https://travis-ci.org/JuliaDynamics/DynamicalBilliards.jl#L640

It is clear that this is a Python and not Julia error, since there is a version mismatch for mkdocs. The thing is, I read through the configuration docpage of MkDocs and could not find a way to specify the version. Then I realized that I actually install MkDocs through Documenter.

My make.jl is:

using Documenter, DynamicalSystems

makedocs(modules=[DynamicalSystems], doctest=false)

deploydocs(
    deps   = Deps.pip("mkdocs",
    "mkdocs-material" ,"python-markdown-math", "pygments", "pymdown-extensions"),
    repo   = "github.com/JuliaDynamics/DynamicalSystems.jl.git",
    julia  = "0.6",
    osname = "linux"
)

Of course I can also post the mkdocs.yml if you'd like.

I saw the source for Deps.pip but it simply passes the input to pip.

Can I somehow solve this? Can I give some command to deploydocs to resolve this version mismatch? Thanks a lot for any help.

[mortenpi]

Not exactly sure what is going here. It seems that MkDocs does not get installed properly. MkDocs 0.17.0 was released recently, but other builds have passed without issues. Have you tried restarting the build? It could be some weird intermittent issue.

On a side tangent: I think you can remove the docs/site directory -- this should be created by MkDocs.

[Datseris]

Yes I have restarted the build many times over. Weirdly, it happens to both of my repos (the one posted here and the other being in the same link but with DynamicalSystems.jl instead). I restarted again but it didn't work...

About the docs/site, how can I remove it? The directory does not exist in my repo on github. I looked the branch gh-pages but it simply has a bunch of folders.

Thank you for helping my by they way. I am lost with this and it is kind of important since there has been some change in an API but it is not reflected in the docs...

[mortenpi]

Nothing has changed in Documenter that should cause this, but there might be some sort of a bug. I'll fork the repo and see if I can replicate it.

The directory does not exist in my repo on github.

Yes, it does exist on the master branch: https://github.com/JuliaDynamics/DynamicalBilliards.jl/tree/master/docs/site

[Datseris]

Oh sorry, I messed up, because I was looking at the DynamicalSystems.jl repo: https://github.com/JuliaDynamics/DynamicalSystems.jl/tree/master/docs
which has the same problem (identical error message stacktrace).

I will delete it now in hope of fixing it then!

[mortenpi]

So I SSHd into a debug build and looked around. It turns out that the material theme has a fixed MkDocs requirement (0.16.3) and has not yet been updated to MkDocs 0.17.0. This in turn is due to some problems with themes in MkDocs 0.17.0: mkdocs/mkdocs#1316 squidfunk/mkdocs-material#513

If I understand correctly, it will hopefully be fixed in a few days when a bugfix of MkDocs gets released: https://github.com/mkdocs/mkdocs/issues/1316#issuecomment-339020650

But to temporarily work around it you could pin MkDocs to 0.16.3 in make.jl:
` deploydocs( deps = Deps.pip("mkdocs==0.16.3", "mkdocs-material", ...), ... )

[mortenpi]

It seems that partially this is caused by pips slightly problematic dependency resolution. If you call pip install mkdocs mkdocs-material, then pip does not take into account that mkdocs-material requires an older mkdocs and simply installs the latest. If you pip install them separately, then pip uninstalls mkdocs 0.17.0 and install 0.16.3 as it should.

So a thing we could do on Documenter's end is to call pip install separately for each deps item in Deps.pip.

[Datseris]

@mortenpi Thank you soooo much. Your suggestion "mkdocs==0.16.3" worked perfectly fine. I have build the docs in one of my repos and now I will proceed to the second. Also thank you for the detailed explanation of what was wrong, I understood everything!

I will follow this issue on squidfunk so I can change back the mkdocs version when it is resolved.

Thanks so much for helping me, seriously!!!