Doctest fixing can't find doctests in files with CRLF line endings

[AshlinHarris]

https://juliadocs.github.io/Documenter.jl/stable/man/doctests/#Fixing-Outdated-Doctests https://juliadocs.github.io/Documenter.jl/dev/man/doctests/#Fixing-Outdated-Doctests

The documentation for Documenter.jl mentions a fix argument for updating doctests, but this seems to have been patched out in src/Documenter.jl. What is the status of this feature?

[mortenpi]

I am not quite sure what you mean..? The functionality is very much there:

https://github.com/JuliaDocs/Documenter.jl/blob/ebe2f97acc9e37c87f7f44772ebf64492c5b0b21/src/Documenter.jl#L909-L931 https://github.com/JuliaDocs/Documenter.jl/blob/ebe2f97acc9e37c87f7f44772ebf64492c5b0b21/src/DocTests.jl#L329-L331

[AshlinHarris]

You're right, I was passing the argument to makedocs() instead of doctest(). My mistake!

[AshlinHarris]

I'm able to run using Documenter, MyPackage; doctest(MyPackage, fix=true) from the REPL, but I still get warning messages like the user in Issue #1782:

Warning: could not find code block in source file

Running doctest(MyPackage) gives the following as expected output for the tests:

ERROR: UndefVarError: my_function not defined

I am using REPL style doctests, so I'm not sure if there is an issue with how Documenter parses these, or if I'm just not supplying the information it needs.

[mortenpi]

I think I've also noticed that happening sometimes, so it does seem like something goes wrong in the fixing logic sometimes. Would need an MWE to debug this though.. did you run into this with PreprocessMD?

By the way, for what it's worth, you can also pass doctest = :fix to makedocs (as you can see, that's actually what doctest() does internally).

[AshlinHarris]

It turns out the issue only happens on Windows. Passing doctest = :fix to makedocs works fine on Linux. I'm also using Julia 1.7.2 instead of 1.7.3, by the way.

I had been testing things with PreprocessMD, but I'll put together a small MWE. Thanks so much for your time!

[AshlinHarris]

Here is my best attempt at a MWE: mwe.txt

Running julia mwe.txt in an empty directory should generate the entire package from scratch, including writing in the source code. Unfortunately, the call to doctest() doesn't edit the source code as I expected. I looked over the documentation and my own work on PreprocessMD from a few months ago, and I'm still not sure what is missing.

I suspect that any working example of doctest(fix=true) which modifies a broken test will fail on Windows,

[mortenpi]

Thanks Ashlin! I was able to replicate it and, and it looks like the issue is that we can't find the doctest when CRLF line endings are used for the source file. This is most like because we normalize the line endings somewhere. The following MWE also fails on Linux, since I enforce CRLF in the source file: https://gist.github.com/mortenpi/7c08f94943b60dda9ec4401bba48b271

It makes sense that this is intermittent on Windows --- if you're working with other people's code, it likely has LF line endings already, but e.g. new files may have CRLF. For a workaround, you try to see if you can enforce LF line endings on your files when you save them.

I also have a strong hunch that #1782 is a duplicate of this.

[AshlinHarris]

Great catch! The issues shows up only when there is an outdated test in a CRLF file. Enforcing LF is good advice. Many thanks!