Comments (19)
It seems to me that
{repl}
is not redirecting correctlySTDOUT
andSTDERR
.
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.
Related Issues (20)
- Alternative admonition syntax?
- Support for external parsers like CommonMark HOT 2
- Profiling docs build times HOT 3
- Not Matching Versions for Subpackage Version Tags HOT 1
- docstrings in extensions HOT 1
- Add a note to contributor docs about how to format code
- Add `make` command to run prettier
- Deserialization in Julia code blocks can throw an error. HOT 2
- proposal for rendering images when last value from @example blocks HOT 5
- Generated files with Documenter.jl and julia-docdeploy have random characters included in their name, not rendering correctly HOT 4
- Feature request: Cross module links HOT 2
- (Perhaps) Incorrectly interpreting square brackets in docstrings as links HOT 3
- Undesirable `Main.var"Main"` qualification of new modules HOT 2
- html field type not implemented HOT 1
- Can we make search modify the URL HOT 4
- Erroneous Errors with `checkdocs`
- Feature request: ANSI color output in reference documentation HOT 6
- Option to Disable collapse/expand HOT 2
- How to use `@repl` and `@example` in docstring?
- Linkcheck failing because of user agent used by Documenter
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from documenter.jl.