Issues with multiple named `{repl}` about documenter.jl HOT 19 CLOSED

It seems to me that {repl} is not redirecting correctly STDOUT and STDERR.

Currently, thrown errors will abort execution of a {repl} block and just splice in the original code block. So this one is expected at the moment, but can be changed relatively easily to rather print the error and continue. Will fix this one.

Warnings and info messages are not displayed

Does it not output something like the following:

...
Documenter: expanding markdown templates.
 !! failed to run code block.

DivideError() [src/tests.md]
...

using nothing # hide to suppress output

Should just support using ; for this. Can also be fixed quite easily.

The context is two files which use named {repl} blocks which are independent.

Could you provide a working example if possible? I'm having trouble replicating this at the moment on Linux. (Perhaps platform dependant?)

from documenter.jl.

Thanks for taking care of this. I find extremely useful this feature, among others, because it keeps the documentation without my intervention.

Regarding the info messages, there is no error message. The ; at the end indeed suppresses the output (as expected), including the STDOUT (the relevant output from @time is what I'd like to keep).

I forgot to mention that the weird error appears during the cross-references building process (which may explain that the markdown files in build/ appear ok. I also noticed that, if I introduce a true error, the weird error disappears.

I have created a branch of our project where you can find everything. The branch is "docs_err" and the project is TaylorSeries.jl; some lines are changed with respect to what I'd like to illustrate, just for convenience now. The two relevant files are user_guide.md and examples.md. In the first one, if you uncomment the line # 1/t^3.2 (third {repl} block), that will cause an error which allows the whole make.jl to complete. In the second file, the lines with @time should only displayed the output from @time but they don't. Without the ; (second instance) they yield the whole output; with ; the output is completely suppressed.

from documenter.jl.

Thanks for providing the extra info. I'll see if I can look into this tomorrow or Monday.

from documenter.jl.

Capturing errors and handling ; correctly have been added in the referenced commit. Do let me know if it's sufficient. Note that currently it's not displaying the backtrace associated with the error since they're generally quite noisy, can be cleaned up in a later commit though.

from documenter.jl.

For my current needs, what you have done already is sufficient. From the initial list, the second point is completely solved. As for the first one, errors and warnings seem to work fine, but info("Something") does not behave as expected. The third item, the weird error, is still there, but is really weird. I'll try to find the origin of the problem.

from documenter.jl.

One more observation about the weird error:

In TaylorSeries.jl (on branch docs_err, in the file user_guide.md), if I delete the very last {repl} block, the process of building up the documentation runs completely and without the error. Conversely, if I keep only that {repl} block (together with some other to avoid trivial errors), again everything works fine.

from documenter.jl.

I'll be getting back to solving the outstanding issues here in the next few days, apologies for the delays.

from documenter.jl.

No problem, and thanks for taking the time!

from documenter.jl.

This is an update to this issue.

I have changed the documentation to use the new syntax of our package (thanks for the changes!).
Long story short, I still get the weird error; you can reproduce it using the current branch docs_err. What I get is the following output:

$ julia make.jl
Documenter: setting up build directory.
Documenter: copying assets to build directory.
 !! Overwriting 'build/assets/Documenter.css'.
 !! Overwriting 'build/assets/mathjaxhelper.js'.
Documenter: expanding markdown templates.
Documenter: building cross-references.
Documenter: running document checks.
ERROR (unhandled task failure): readcb: bad file descriptor (EBADF)
 in yieldto at /usr/local/julia/julia-d829429d34/lib/julia/sys.dylib
 in wait at /usr/local/julia/julia-d829429d34/lib/julia/sys.dylib (repeats 2 times)
 in wait_readnb at ./stream.jl:374
 in eof at ./stream.jl:96
 in watchbuffer at /Users/benet/.julia/v0.4/Documenter/src/modules/DocChecks.jl:353
 in anonymous at ./task.jl:447
 !! 1 docstring potentially missing:

    TaylorSeries

 !! Skipped doctesting.
Documenter: rendering document.
Documenter: skipping docs deployment.

After the last line, the process hangs without ending, so I have to kill it (ctrl z).

I have been trying to understand what is going on, but my knowledge is too limited. Clearly a task is not ending properly. If I naively add a new line print(".") after result is computed in the function withoutput (say, a new line 347 in src/modules/DocChecks.jl), the documentation is built nicely and the process ends without the error above.

Any idea why this behaves like that?

from documenter.jl.

Thanks for the update, this one has been tricky to try and recreate on either 0.4 or 0.5 Linux hence to lack of progress here. Are you able to test on something other than 0.4 OSX to check you can recreate this?

It's definitely something to do with creating too many tasks I believe. There's nothing in your docs/ folder that stands out as being the cause. I think the best approach will probably be to only start up a single output redirection task and then reuse it for each @repl/@example block rather than a new one for each.

from documenter.jl.

I will try it on a linux machine, though I have to set up the needed library first.

If there are too many tasks spawn, why then is my naive solution working?

from documenter.jl.

Not too sure really. Does it still fix it if you just put print() rather than print(".")?

from documenter.jl.

Also, does this diff do anything to help?

diff --git a/src/modules/DocChecks.jl b/src/modules/DocChecks.jl
index 2497ab4..08a0e7e 100644
--- a/src/modules/DocChecks.jl
+++ b/src/modules/DocChecks.jl
@@ -350,9 +350,10 @@ end

 # Sends all data from `from` to `to`. Exits when `killed` is set to `true`.
 function watchbuffer(from::IO, to::IO, killed::Ref)
-    while !eof(from) || !killed[]
+    while !eof(from)
         n = nb_available(from)
         n > 0 ? write(to, read(from, n)) : 0
+        killed[] && break
     end
 end

from documenter.jl.

Both suggestions yield the same error and hang the process.

from documenter.jl.

Thanks for checking those.

from documenter.jl.

I just checked whether the same problem appears using julia 0.4 in a linux machine, and things work perfectly there. So, I simply checked what are the limits for the resources on my mac and on the linux box. Increasing the number of open files (ulimit -n 1024, the default was 256) is enough to get things working. Incidentally, julia 0.5 in my mac was not having this issue.

from documenter.jl.

Excellent! Thanks for investigating that.

Incidentally, julia 0.5 in my mac was not having this issue.

Perhaps it's a bug that's been fixed on master, though I don't recall anything similar to this recently.

from documenter.jl.

It seems that travis has the same problem I was having; see https://travis-ci.org/JuliaDiff/TaylorSeries.jl/jobs/136577543

I tried to solve it by adding osname = "linux" but it didn't work either. So, for the time being, I will remove travis tests on osx.

from documenter.jl.

Closed by #93.

from documenter.jl.