Mkdocs_material in documenter

I’ve a question on mkdocs run in Documenter on Travis - the mkdocs-material theme fails with the message

Downloading https://files.pythonhosted.org/packages/03/11/8ab0881bb6fe76e22d636c8327e86c2738f0d96f0d2145fec7e4fa7de9df/mkdocs_material-3.0.3-py2.py3-none-any.whl (574kB)
Collecting mkdocs>=1 (from mkdocs-material)
  Could not find a version that satisfies the requirement mkdocs>=1 (from mkdocs-material) (from versions: 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8, 0.9, 0.10, 0.11, 0.11.1, 0.12.0, 0.12.1, 0.12.2, 0.13.0, 0.13.1, 0.13.2, 0.13.3, 0.14.0, 0.15.0, 0.15.1, 0.15.2, 0.15.3, 0.16.0, 0.16.1, 0.16.2, 0.16.3, 0.17.0, 0.17.1, 0.17.2, 0.17.3, 0.17.4, 0.17.5)
No matching distribution found for mkdocs>=1 (from mkdocs-material)
You are using pip version 9.0.1, however version 18.0 is available.
You should consider upgrading via the 'pip install --upgrade pip' command.
ERROR: LoadError: failed process: Process(`pip install --user mkdocs-material`, ProcessExited(1)) [1]
Stacktrace:
 [1] error(::String, ::Base.Process, ::String, ::Int64, ::String) at ./error.jl:42
 [2] pipeline_error at ./process.jl:695 [inlined]
 [3] #run#505(::Bool, ::Function, ::Cmd) at ./process.jl:653
 [4] run at ./process.jl:651 [inlined]
 [5] pip(::String, ::Vararg{String,N} where N) at /home/travis/.julia/packages/Documenter/bK0Xg/src/Deps.jl:34
 [6] top-level scope at none:0
 [7] include at ./boot.jl:317 [inlined]
 [8] include_relative(::Module, ::String) at ./loading.jl:1038
 [9] include(::Module, ::String) at ./sysimg.jl:29
 [10] include(::String) at ./client.jl:388
 [11] top-level scope at none:0
in expression starting at /home/travis/build/JuliaPlots/PlotDocs.jl/docs/make.jl:5

The offending line in make.jl is deps = Deps.pip("mkdocs", "mkdocs-material" ,"python-markdown-math", "pygments", "pymdown-extensions")
Does mkdocs-material not work anymore, or am I doing something wrong?

1 Like

What’s the Python version? The python_requires for mkdocs is https://github.com/mkdocs/mkdocs/blob/master/setup.py#L66.
MkDocs 1.0 does indeed exist on pip https://pypi.org/project/mkdocs/.

How do I find out? this is on Travis and we seem to not be specifying the python version. It doesn’t complain when I run it on my local machine.

This came up once before already. I don’t know if @Datseris figured out the solution.

But yes, the problem is that the Python version on Travis is like ~2.7.3 or something, whereas MkDocs 1.0 needs at least 2.7.9, so it installs an older MkDocs. However, the latest mkdocs-material needs MkDocs 1.0., so it fails to install All in all, it looks like pip just spectacularly fails to resolve versions here.

Specifying the versions of MkDocs and mkdocs-material by hand might work. You could try passing

deps = Deps.pip("mkdocs==0.17.5", "mkdocs-material==2.9.4" ,"python-markdown-math", "pygments", "pymdown-extensions")
4 Likes

That fixed it - thank you!

I am now following use-conda-with-travis-ci to use the latest Mkdocs.

Do you have a public package where this is working? I would like to peek at your travis.yml.

Hi, it isn’t public yet but I paste them below:

## Documentation: http://docs.travis-ci.com/user/languages/julia/
language: julia
os:
  - linux
  - osx
julia:
  - 1.0
  - nightly
matrix:
  allow_failures:
    - julia: nightly
  fast_finish: true
notifications:
  email: false
branches:
  only:
    - master
    - /^v[0-9]+\.[0-9]+\.[0-9]+$/
after_success:
  - julia --project=test/coverage -e 'using Pkg; Pkg.instantiate()'
  - julia --project=test/coverage test/coverage/coverage.jl
jobs:
  include:
    - stage: "Documentation"
      julia: 1.0
      os: linux
      install:
        # mkdocs-material isn't available at the default py2 on travis-ci for now
        - sudo apt-get update
        - wget https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh;
        - bash miniconda.sh -b -p $HOME/miniconda
        - export PATH="$HOME/miniconda/bin:$PATH"
        - conda config --set always_yes yes --set changeps1 no
        - conda update -q conda
        - conda info -a
      script:
        - julia --project=docs -e 'using Pkg; Pkg.instantiate(); Pkg.add(PackageSpec(path=pwd()))'
        - julia --project=docs --color=yes docs/make.jl
      after_success: skip

So basically it uses miniconda3 after installation and path exportation so it has no problem with the latest Mkdocs. You may also check pymdown-extensions, there are lots of useful stuff working with mkdocs-material.

2 Likes

Thanks a lot! This is super useful.

this link is broken.
deps = Deps.pip("mkdocs==0.17.5", "mkdocs-material==2.9.4" ,"python-markdown-math", "pygments", "pymdown-extensions") does not work for me.
neither does that jobs section of the travis.yml file.

I wouldn’t notice that at all without your mention.

The reason is that in my .yml file matrix is an alias of job (which is recommended to use now), thus it overwrites the job below, so the documentation job won’t be executed. To fix that, you may merge the two section together.