Give better instructions for building the docs #2266

odow · 2020-07-05T22:01:54Z

Because the current instructions weren't very clear. See, e.g., #2237 (comment).

mlubin · 2020-07-05T22:04:25Z

Is there any cleaner way to do this?

codecov · 2020-07-05T22:31:02Z

Codecov Report

Merging #2266 (817162c) into master (f47b18c) will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master    #2266   +/-   ##
=======================================
  Coverage   91.61%   91.61%           
=======================================
  Files          42       42           
  Lines        4451     4451           
=======================================
  Hits         4078     4078           
  Misses        373      373

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update f47b18c...817162c. Read the comment docs.

odow · 2020-07-05T23:11:07Z

Is there any cleaner way to do this?

Not really. Because we need the dev'd version of JuMP. Without the add step, we get:

(base) Oscars-MBP:JuMP oscar$ julia --project=docs docs/make.jl
ERROR: LoadError: ArgumentError: Package JuMP not found in current path:
- Run `import Pkg; Pkg.add("JuMP")` to install the JuMP package.

Stacktrace:
 [1] require(::Module, ::Symbol) at ./loading.jl:823
 [2] include at ./boot.jl:317 [inlined]
 [3] include_relative(::Module, ::String) at ./loading.jl:1044
 [4] include(::Module, ::String) at ./sysimg.jl:29
 [5] exec_options(::Base.JLOptions) at ./client.jl:266
 [6] _start() at ./client.jl:425
in expression starting at /Users/oscar/.julia/dev/JuMP/docs/make.jl:1

mlubin · 2020-07-05T23:14:44Z

I'm a bit skeptical, doesn't every package that uses Documenter have the same issue? Is this the workflow they recommend?

odow · 2020-07-05T23:21:17Z

I'm a bit skeptical, doesn't every package that uses Documenter have the same issue? Is this the workflow they recommend?

Seems so. The instructions for Travis also have the "dev then build" workflow:
https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#Travis-CI

Or they suggest modifying LOAD_PATH.
https://juliadocs.github.io/Documenter.jl/stable/man/guide/#Building-an-Empty-Document

We could add JuMP to Project.toml, but people will still have to dev it the first time, and then maybe run ] up to refresh the Manifest.toml before building the docs.

mlubin · 2020-07-05T23:24:13Z

The docs suggest adding push!(LOAD_PATH,"../src/") to make.jl. Does this work? It so, it wouldn't require someone building the docs to fiddle with Pkg.

odow · 2020-07-05T23:28:44Z

Nope. Now that gives

(base) Oscars-MBP:JuMP oscar$ julia --project=docs docs/make.jl
ERROR: LoadError: ArgumentError: Package MutableArithmetics not found in current path:
- Run `import Pkg; Pkg.add("MutableArithmetics")` to install the MutableArithmetics package.

Stacktrace:
 [1] require(::Module, ::Symbol) at ./loading.jl:823
 [2] include at ./boot.jl:317 [inlined]
 [3] include_relative(::Module, ::String) at ./loading.jl:1044
 [4] include(::Module, ::String) at ./sysimg.jl:29
 [5] top-level scope at none:2
 [6] eval at ./boot.jl:319 [inlined]
 [7] eval(::Expr) at ./client.jl:393
 [8] top-level scope at ./none:3
in expression starting at /Users/oscar/.julia/dev/JuMP/src/JuMP.jl:16
ERROR: LoadError: Failed to precompile JuMP [top-level] to /Users/oscar/.julia/compiled/v1.0/JuMP.ji.
Stacktrace:
 [1] error(::String) at ./error.jl:33
 [2] compilecache(::Base.PkgId, ::String) at ./loading.jl:1203
 [3] _require(::Base.PkgId) at ./loading.jl:960
 [4] require(::Base.PkgId) at ./loading.jl:858
 [5] require(::Module, ::Symbol) at ./loading.jl:853
 [6] include at ./boot.jl:317 [inlined]
 [7] include_relative(::Module, ::String) at ./loading.jl:1044
 [8] include(::Module, ::String) at ./sysimg.jl:29
 [9] exec_options(::Base.JLOptions) at ./client.jl:266
 [10] _start() at ./client.jl:425
in expression starting at /Users/oscar/.julia/dev/JuMP/docs/make.jl:2

mlubin · 2020-07-06T01:03:24Z

So what's going on in this sequence? I can build the docs fine without following these instructions.

$ julia
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.0.3 (2018-12-18)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

(v1.0) pkg> st
    Status `~/.julia/environments/v1.0/Project.toml`
  [4076af6c] JuMP v0.21.2 [`~/.julia/dev/JuMP`]

$ julia --project=docs
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.0.3 (2018-12-18)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

(docs) pkg> st
    Status `~/.julia/dev/JuMP/docs/Project.toml`
  [e30172f5] Documenter v0.23.4

julia> using JuMP # Works

$ julia --project=docs docs/make.jl
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Info: Deployment criteria:
│ - ✔ ENV["TRAVIS_REPO_SLUG"]="" occurs in repo="github.com/jump-dev/JuMP.jl.git"
│ - ✘ ENV["TRAVIS_PULL_REQUEST"]="" is "false"
│ - ✔ ENV["TRAVIS_TAG"]="" is (i) empty or (ii) a valid VersionNumber
│ - ✘ ENV["TRAVIS_BRANCH"]="" matches devbranch="master" (if tag is empty)
│ - ✘ ENV["DOCUMENTER_KEY"] exists
│ - ✔ ENV["TRAVIS_EVENT_TYPE"]="" is not "cron"
└ Deploying: ✘

odow · 2020-07-06T01:31:52Z

In the first one, you have dev'd JuMP to your global environment.

I usually hack on projects by cd'ing to their directory, and then starting Julia with julia --project=..

So the options are either

dev JuMP to your global environment
Do the docs environment modification

henriquebecker91 · 2020-07-06T02:36:16Z

Just to chime in, the first time I tried building JuMP I actually had dev .. inside the docs environment because with Julia 1.4.2 (that I was using before) gave a very clear error message (I have not seen the 1.0.5 one), and I had the same problem to generate the docs of my own package, so I was not stopped more than 10~20 seconds by this. This probably happened because I did not install/develop JuMP in the default environment. I have a personal policy of never having anything installed in the default environment unless it becomes clearly necessary, so I had just forked and git cloned the JuMP repo, and tried to build the docs.

I think it is a good idea to improve the documentation for the docs building but, if I am not mistaken, the problems I reported in the specific comment cited in the top of this thread seem to have nothing to do with this. Maybe it will be a little confusing to people coming from that comment, or checking the comment before the messages of this PR, what one thing has to do with the other.

odow · 2020-07-06T12:40:23Z

the problems I reported in the specific comment cited in the top of this thread seem to have nothing to do with this

The error you posted, https://pastebin.com/TPg7kH2a, is weird and it looks like you had some trouble loading MathOptInterface. Why is it replacing HTTP? Why couldn't it generate a compiled JSONSchema? I'm not sure what the cause is, but it probably comes from doing something different to these instructions.

I have a personal policy of never having anything installed in the default environment unless it becomes clearly necessary, so I had just forked and git cloned the JuMP repo, and tried to build the docs.

To clone a package for development, I go

> julia

julia> ] dev NewPackage  # Clones to ~/.julia/dev/NewPackage

julia> ] rm NewPackage  # Removes from global env, but leaves ~/.Julia/dev/NewPackage

Then to hack on it

> cd ~/.julia/dev/JuMP

> git checkout -b od/new_feature

> julia --project=.

henriquebecker91 · 2020-07-06T12:46:59Z

julia> ] rm NewPackage  # Removes from global env, but leaves ~/.Julia/dev/NewPackage

I did not know this trick. I will try it today or tomorrow, and check if it solves the problems.

mlubin · 2020-07-06T14:05:05Z

Should we add a note then about how the distinction between having JuMP "dev'd" in a local or global environment?

henriquebecker91 · 2020-07-06T14:34:36Z

I do not know if it is a bad practice or not. But the solution I adopted for my package was committing the Manifest.toml of the docs folder, so the following lines exist:

[[GuillotineModels]]
deps = ["ArgParse", "Dates", "DocStringExtensions", "JuMP", "MathOptInterface", "Random", "RandomNumbers", "Requires", "Statistics", "TimerOutputs", "UnPack"]
path = ".."
uuid = "300ad42c-a273-11e9-37f6-175a19b744a4"
version = "0.2.0"

The most important, of course, is the path = .. line. This seemed the most natural to me. Because if you want generate documentation inside a package then: (1) you want to be absolutely sure it will generate the documentation relative to the package you are inside the folder, not another deved installation of the package that can end up being loaded from some other place; (2) the documentation itself is not a package in which having the Manifest.toml available is a problem because stacked environments when someone imports the package, nobody will import the docs folder.

henriquebecker91 · 2020-07-07T13:19:02Z

Considering this thread is for giving better doc building instructions I will keep reporting my troubles here, but please tell me if there is a more adequate channel.

What I did:

> mv ~/.julia{,-1.4.2} # save my old .julia
> julia-1.0.5
julia> dev MathOptInterface
julia> rm MathOptInterface
julia> <CTRL-D>
> cd ~/.julia/dev/MathOptInterface/docs
> julia-1.0.5 --project=. make.jl 
ERROR: LoadError: ArgumentError: Package Documenter [e30172f5-a6a5-5a46-863b-614d45cd2de4] is required but does not seem to be installed:
 - Run `Pkg.instantiate()` to install all recorded dependencies.
> julia-1.0.5
julia> ]activate .
julia> ]instantiate
julia> <CTRL-D>
> julia-1.0.5 --project=. make.jl
...
[ Info: Populate: populating indices.
ERROR: LoadError: `makedocs` encountered errors. Terminating build
...

The new complete log error is here. Some of the strange errors of the past try have disappeared this way (like the HTTP one). But the build keeps failing. Did I follow some step wrong? Nobody has the same problem behavior repeating my steps?

odow · 2020-07-07T14:20:44Z

Oscars-MBP:MathOptInterface oscar$ julia --project=docs
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.0.5 (2019-09-09)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

(docs) pkg> dev .
 Resolving package versions...
  Updating `~/.julia/dev/MathOptInterface/docs/Project.toml`
  [b8f27783] + MathOptInterface v0.9.14 [`..`]
  Updating `~/.julia/dev/MathOptInterface/docs/Manifest.toml`
  [6e4b80f9] + BenchmarkTools v0.5.0
  [b99e7846] + BinaryProvider v0.5.10
  [523fee87] + CodecBzip2 v0.6.0
  [944b1d66] + CodecZlib v0.6.0
  [cd3eb016] + HTTP v0.8.16
  [83e8ac13] + IniFile v0.5.0
  [7d188eb4] + JSONSchema v0.3.0
  [b8f27783] + MathOptInterface v0.9.14 [`..`]
  [739be429] + MbedTLS v0.6.8
  [d8a4904e] + MutableArithmetics v0.2.10
  [bac558e1] + OrderedCollections v1.3.0
  [3bb67fe8] + TranscodingStreams v0.9.5
  [a5390f91] + ZipFile v0.8.4
  [2f01184e] + SparseArrays 
  [10745b16] + Statistics 

(docs) pkg> instantiate
  Updating registry at `~/.julia/registries/General`
  Updating git-repo `https://github.com/JuliaRegistries/General.git`

julia> exit()
Oscars-MBP:MathOptInterface oscar$ julia --project=docs docs/make.jl
[ Info: SetupBuildDirectory: setting up build directory.
[ Info: Doctest: running doctests.
[ Info: ExpandTemplates: expanding markdown templates.
[ Info: CrossReferences: building cross-references.
[ Info: CheckDocument: running document checks.
[ Info: Populate: populating indices.
[ Info: RenderDocument: rendering document.
[ Info: HTMLWriter: rendering HTML pages.
┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
└ @ Documenter ~/.julia/packages/Documenter/PLD7m/src/deployconfig.jl:41
Oscars-MBP:MathOptInterface oscar$ julia --project=docs
               _
   _       _ _(_)_     |  Documentation: https://docs.julialang.org
  (_)     | (_) (_)    |
   _ _   _| |_  __ _   |  Type "?" for help, "]?" for Pkg help.
  | | | | | | |/ _` |  |
  | | |_| | | | (_| |  |  Version 1.0.5 (2019-09-09)
 _/ |\__'_|_|_|\__'_|  |  Official https://julialang.org/ release
|__/                   |

(docs) pkg> st
    Status `~/.julia/dev/MathOptInterface/docs/Project.toml`
  [e30172f5] Documenter v0.24.11
  [b8f27783] MathOptInterface v0.9.14 [`..`]

(docs) pkg> up
  Updating registry at `~/.julia/registries/General`
  Updating git-repo `https://github.com/JuliaRegistries/General.git`
 Resolving package versions...
  Updating `~/.julia/dev/MathOptInterface/docs/Project.toml`
 [no changes]
  Updating `~/.julia/dev/MathOptInterface/docs/Manifest.toml`
 [no changes]

(docs) pkg> st
    Status `~/.julia/dev/MathOptInterface/docs/Project.toml`
  [e30172f5] Documenter v0.24.11
  [b8f27783] MathOptInterface v0.9.14 [`..`]

docs/README.md

odow · 2020-12-03T21:34:48Z

Thanks for the review. I just pushed greatly simplified instructions.

odow mentioned this pull request Jul 5, 2020

set_start_value only accept numbers #2237

Closed

blegat approved these changes Jul 6, 2020

View reviewed changes

matbesancon reviewed Dec 3, 2020

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

matbesancon reviewed Dec 3, 2020

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

matbesancon reviewed Dec 3, 2020

View reviewed changes

docs/README.md Outdated Show resolved Hide resolved

odow and others added 3 commits December 4, 2020 10:22

Give better instructions for building the docs

de4b649

[ci skip] Fix whitespace

ac45739

Simplify documentation instructions

e2c01f6

odow force-pushed the odow-patch-2 branch from 5d4641f to e2c01f6 Compare December 3, 2020 21:33

Update README.md

817162c

odow merged commit 52020e3 into master Dec 6, 2020

odow deleted the odow-patch-2 branch December 6, 2020 20:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Give better instructions for building the docs #2266

Give better instructions for building the docs #2266

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020

codecov bot commented Jul 5, 2020 •

edited

Loading

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020 •

edited

Loading

odow commented Jul 5, 2020

mlubin commented Jul 6, 2020

odow commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020 •

edited

Loading

odow commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020

mlubin commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020

henriquebecker91 commented Jul 7, 2020

odow commented Jul 7, 2020

odow commented Dec 3, 2020

Give better instructions for building the docs #2266

Give better instructions for building the docs #2266

Conversation

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020

codecov bot commented Jul 5, 2020 • edited Loading

Codecov Report

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020

odow commented Jul 5, 2020

mlubin commented Jul 5, 2020 • edited Loading

odow commented Jul 5, 2020

mlubin commented Jul 6, 2020

odow commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020 • edited Loading

odow commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020

mlubin commented Jul 6, 2020

henriquebecker91 commented Jul 6, 2020

henriquebecker91 commented Jul 7, 2020

odow commented Jul 7, 2020

odow commented Dec 3, 2020

codecov bot commented Jul 5, 2020 •

edited

Loading

mlubin commented Jul 5, 2020 •

edited

Loading

henriquebecker91 commented Jul 6, 2020 •

edited

Loading