Use julia-repl in manual & other edits by mortenpi · Pull Request #21866 · JuliaLang/julia

mortenpi · 2017-05-14T04:26:00Z

Use julia-repl to highlight REPL blocks in the manual, which makes them consistent with doctest blocks. Requires Documenter v0.10.1, which is why it's currently based on #21846.

I also came across a number of REPL blocks that seemed like they could be turned into doctests as well, and a few other small things. However, I guess there might have been a good reason why some of them were not enabled, so I'd be happy to drop some or all of those commits if need be.

I think it would be good to get this backported to 0.6 as well, at least the first commit. It seems that there's only one tiny conflict, so it shouldn't be a big problem.

Example build: http://mortenpi.eu/julia/julia-repl/index.html

mortenpi · 2017-05-14T04:28:57Z

doc/src/devdocs/backtraces.md

-  LIBM: libopenlibm
-  LLVM: libLLVM-3.3
+```@repl
+versioninfo()


This change would also require a small bugfix in Documenter (JuliaDocs/Documenter.jl#484).

tkelman · 2017-05-14T11:34:52Z

doc/src/devdocs/subarrays.md

 happens to be uniform:

-```julia
+```julia-repl


doctest candidate?
(also the next one in this file)

Ideally we'd doctest a lot more in this file, but we'd need a way to run ordinary code within doctests. A named @example block sharing scope with doctests could be a way maybe, but Documenter doesn't support that at the moment afaict.

tkelman · 2017-05-14T11:37:02Z

doc/src/manual/arrays.md

 are needed to separate the generator from subsequent arguments:

-```julia
+```julia-repl


doctest candidate? in case the error message changes I suppose

Documenter can't handle syntax errors as far as I can tell (at the moment, should probably be fixed).

Ah my mistake then. Is there a tracking issue?

There is now: JuliaDocs/Documenter.jl#487 Also, the same applies to the invalid UTF-8 example in manual/strings.md.

tkelman · 2017-05-14T11:38:32Z

doc/src/manual/conversion-and-promotion.md

 doesn't know how to perform the requested conversion:

-```julia
+```julia-repl


doctest too for the error message?

KristofferC · 2017-05-14T11:39:49Z

I'm not sure I understand why both julia and julia-repl need to exist? What is the difference?

tkelman · 2017-05-14T11:57:28Z

doc/src/manual/packages.md


-```julia
+```julia-repl
 $ echo UTF16 >> ~/.julia/v0.6/REQUIRE


we may want to change this example to a non-deprecated package

tkelman · 2017-05-14T14:21:32Z

doc/src/manual/running-external-programs.md

 More generally, you can use [`open()`](@ref) to read from or write to an external command.

-```julia
+```julia-repl


doctestable?

tkelman · 2017-05-14T14:25:31Z

doc/src/manual/strings.md

 a regular string literal, you will get a syntax error:

-```julia
+```julia-repl


could doctest the error

tkelman · 2017-05-14T14:27:18Z

doc/src/manual/variables-and-scoping.md

 when it would change the semantics is (currently) a syntax error:

-```julia
+```julia-repl


doctest for the error?

tkelman · 2017-05-14T14:28:34Z

doc/src/manual/variables-and-scoping.md

 have a private state, for instance the `state` variable in the following example:

-```julia
+```julia-repl


this, and the next in this file's diff, should also be testable?

tkelman · 2017-05-14T14:33:14Z

doc/src/stdlib/test.md

 For example, suppose we want to check our new function `foo(x)` works as expected:

-```julia
+```julia-repl


could we put the series in this file in a common named doctest set?

In principle this should be doable, but it's a bit more work. I'd leave this for another day.

ararslan · 2017-05-14T16:04:29Z

@KristofferC The julia definition highlights code blocks as programs. That is, every keyword is highlighted. When used as we do throughout the docs, to simulate a REPL session, the output is also highlighted as though it were code. The difference with julia-repl is that it highlights the julia> prompt and all code that's part of the input, but applies no highlighting to the output. Basically it better simulates what a REPL session looks like.

mortenpi · 2017-05-17T08:51:33Z

doc/src/manual/methods.md

 of those methods are, use the [`methods()`](@ref) function:

-```julia
+```julia-repl


This can't be a doctest at the moment since Documenter thinks that the first line of output is a comment that should be ignored (JuliaDocs/Documenter.jl#483).

mortenpi · 2017-05-17T08:53:58Z

Rebased and all the doctests seem to be passing now. I can squash some of the commits (e.g. all the "Enable doctests in ..." ones) if need be, but I was trying to keep distinct changes in separate commits.

KristofferC · 2017-05-17T08:56:47Z

Great with so many more doctests!

tkelman · 2017-05-17T12:42:13Z

base/regex.jl

 For example, this regex has all three flags enabled:

-```julia
+```julia-repl


did I comment on this one or miss it, seems doctestable?

StefanKarpinski · 2017-05-20T16:31:29Z

We could probably add some smarts to a single julia highlight mode so that it understands when a code block looks like a REPL interaction and does the right thing, but I think having these be different modes is ok too – it provides useful semantic information and it's not all that onerous to mark the two kinds of blocks differently.

mortenpi · 2017-05-21T01:51:21Z

We could probably add some smarts to a single julia highlight mode

Someone has to implement that in highlight.js though. As you point out, there are pros and cons to both approaches, so I'm actually neutral on the matter. For some data: other languages in highlight.js seem to have separate lang-repl modes, and both Atom's language-julia and Pygments have a separate grammar/lexer for Julia's REPL syntax -- although that might be just because it's easier to implement it this way.

However, in any case, switching back to a single julia mode would be simple and non-breaking, so we could easily go with julia-repl for now and change back later if we want, I think.

KristofferC · 2017-05-24T09:24:32Z

Barring objections I plan to merge this later today.

ararslan · 2017-05-24T17:47:27Z

It would be good to squash some of the commits first; 23 is a lot of separate commits for this.

With the highlighting updates in Documenter v0.10.1 it is now possible to have specialized highlighting for REPL blocks via the julia-repl attribute on code blocks. Doctests already use this, so this makes the highlighting for non-doctest REPL blocks consistent.

A couple of code examples were not highlighted for some reason.

These blocks are not Julia code, but special REQUIRE file syntax instead.

Also add a newline to the end of the file.

UTF16.jl has been deprecated for a while. Use SHA.jl instead as the example.

mortenpi · 2017-05-25T04:47:22Z

Done, down to 11 now. I squashed the similar ones. I left the doctest ones under base/ separate, so it would be a bit easier with any potential merge conflicts, should they get backported.

The REPL example is basically exactly as above, and does not add anything to the latter bit about the actual convert methods.

Switching to julia-repl revealed several code blocks that could trivially be turned into doctests.

ararslan · 2017-05-25T16:16:46Z

Perfect. Thanks, @mortenpi!

With the highlighting updates in Documenter v0.10.1 it is now possible to have specialized highlighting for REPL blocks via the julia-repl attribute on code blocks. Doctests already use this, so this makes the highlighting for non-doctest REPL blocks consistent. (cherry picked from commit 014c5d5) ref #21866 Use at-repl for versioninfo() output (cherry picked from commit f67d4fd) Enable highlighting in the manual A couple of code examples were not highlighted for some reason. (cherry picked from commit b710de9) Remove highlighting from REQUIRE code These blocks are not Julia code, but special REQUIRE file syntax instead. (cherry picked from commit c90c17f) Enable bash highlighting Also add a newline to the end of the file. (cherry picked from commit 6e08c18) Use a non-deprecated package in an example UTF16.jl has been deprecated for a while. Use SHA.jl instead as the example. (cherry picked from commit 6e5c55d) Edit manual/conversion-and-promotion.md The REPL example is basically exactly as above, and does not add anything to the latter bit about the actual convert methods. (cherry picked from commit 96b65f1) Fix line numbers in doctests (cherry picked from commit 814a8a1) Enable a doctest in base/regex.jl (cherry picked from commit d9063cb) Enable doctests the the manual Switching to julia-repl revealed several code blocks that could trivially be turned into doctests. (cherry picked from commit 1d20519)

mortenpi commented May 14, 2017

View reviewed changes

ararslan added the docsystem The documentation building system label May 14, 2017

tkelman added the backport pending 0.6 label May 14, 2017

tkelman reviewed May 14, 2017

View reviewed changes

mortenpi force-pushed the mp/julia-repl branch from cb6bd24 to e9da26a Compare May 17, 2017 08:42

mortenpi commented May 17, 2017

View reviewed changes

tkelman reviewed May 17, 2017

View reviewed changes

mortenpi force-pushed the mp/julia-repl branch from fbbb52d to c494662 Compare May 17, 2017 21:47

ararslan approved these changes May 19, 2017

View reviewed changes

mortenpi added 5 commits May 25, 2017 16:35

Use at-repl for versioninfo() output

f67d4fd

Enable highlighting in the manual

b710de9

A couple of code examples were not highlighted for some reason.

Remove highlighting from REQUIRE code

c90c17f

These blocks are not Julia code, but special REQUIRE file syntax instead.

Enable bash highlighting

6e08c18

Also add a newline to the end of the file.

Use a non-deprecated package in an example

6e5c55d

UTF16.jl has been deprecated for a while. Use SHA.jl instead as the example.

mortenpi force-pushed the mp/julia-repl branch from c494662 to d7af1aa Compare May 25, 2017 04:44

mortenpi added 5 commits May 25, 2017 16:49

Edit manual/conversion-and-promotion.md

96b65f1

The REPL example is basically exactly as above, and does not add anything to the latter bit about the actual convert methods.

Fix line numbers in doctests

814a8a1

Fix a doctest in base/path.jl

a64bcf8

Enable a doctest in base/regex.jl

d9063cb

Enable doctests the the manual

1d20519

Switching to julia-repl revealed several code blocks that could trivially be turned into doctests.

mortenpi force-pushed the mp/julia-repl branch from d7af1aa to 1d20519 Compare May 25, 2017 04:50

KristofferC merged commit eaace3b into JuliaLang:master May 25, 2017

mortenpi deleted the mp/julia-repl branch May 25, 2017 22:25

tkelman removed the backport pending 0.6 label Jun 7, 2017

Uh oh!

Conversation

mortenpi commented May 14, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tkelman May 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

KristofferC commented May 14, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tkelman May 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tkelman May 14, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ararslan commented May 14, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mortenpi commented May 17, 2017

Uh oh!

KristofferC commented May 17, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

StefanKarpinski commented May 20, 2017

Uh oh!

mortenpi commented May 21, 2017

Uh oh!

KristofferC commented May 24, 2017

Uh oh!

ararslan commented May 24, 2017

Uh oh!

mortenpi commented May 25, 2017

Uh oh!

ararslan commented May 25, 2017

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

tkelman May 14, 2017 •

edited

Loading

tkelman May 14, 2017 •

edited

Loading

tkelman May 14, 2017 •

edited

Loading