Content for Development environments/Running code #3

jacobusmmsmit · 2023-06-23T12:34:05Z

This PR is mostly a test PR to

See if I can write content using the right formatting such that it appears on the GH page,
Lay out my plans for the structure of the "loading and running" section such that it can be taken into account when writing other sections,
Throw out some comments about the structure of the content in general.

In particular here are some things to look at @gdalle (more detail in comments in file):

I think Revise should be moved to the next section on packages,
The VSCode part of this section should be written with/after the previous one on IDEs so there's no overlap in content and it flows better,
What should go in the startup.jl we provide? Should we provide one? It is my current opinion that it should be minimal. I'm always scared off by long vim configs (for example).

pages/writing.md

jacobusmmsmit · 2023-07-08T16:14:07Z

Some parts are still a skeleton of the final content, but there's enough actual content for me to mark this as an actual PR so others writing can see what's already been written.

pages/writing.md

gdalle · 2023-07-08T21:35:43Z

pages/writing.md

+### Help mode (`?`)
+By entering a `?`, you can query information and metadata about Julia objects and unicode symbols simply by typing their name into the command line.
+For functions, types, and variables, the query fetches things such as documentation, type fields and supertypes, and in which file the object is defined.
+<!-- How do you do syntax highlighting for the Julia REPL? -->


with triple backtick followed by julia-repl

gdalle · 2023-07-08T21:36:13Z

pages/writing.md

+For functions, types, and variables, the query fetches things such as documentation, type fields and supertypes, and in which file the object is defined.
+<!-- How do you do syntax highlighting for the Julia REPL? -->
+```
+help?> Int


it would be nice for this to be run by Franklin itself

tlienart/Franklin.jl#818

gdalle · 2023-07-08T21:42:02Z

pages/writing.md

@@ -45,23 +45,131 @@ juliaup status

 ## Development environments

+Depending on your experience and how you use Julia, some ways of writing code may be more familiar or useful to you than others.


I'll add more details there

gdalle · 2023-07-08T21:42:17Z

pages/writing.md

+Data scientists commonly prefer notebook environments such as those provided by [Jupyter](https://jupyter.org/) through the [IJulia.jl](https://github.com/JuliaLang/IJulia.jl) package, or Julia's own reactive notebooks from [Pluto.jl](https://plutojl.org/).
+On the other hand, package developers or those who write a lot of scripts will prefer the more traditional programming environment provided by a text editor or integrated development environment (IDE).
+
+For some, the Julia REPL (Read Evaluate Print Loop) itself is all that's necessary.


Maybe the REPL deserves its own section before dev envs

gdalle · 2023-07-08T21:42:54Z

pages/writing.md

+Shell mode: Functions as a terminal inside Julia, you can also execude shell commands from Julian mode.
+Here's an example
+```julia
+an_example()


ran out of energy

What are the terminal niceties we might be interested in for this part? The one that comes to mind is git

Git is one, but what I meant to show in this example is calling bash commands from inside a non-interactive Julia session. Calling shell commands from inside Julia means anything Julia can't do but bash can, can be done without needing to worry about interop.

gdalle · 2023-07-08T21:43:55Z

pages/writing.md

+
+[^1]: Unless you're compiling binaries with [StaticTools.jl](https://github.com/brenhinkeller/StaticTools.jl).
+
+<!-- The VSCode is important to write in tandem with or after the Development environments part is written to avoid overlap. -->


Yeah I'm gonna reorder a bit once we merge this

gdalle · 2023-07-08T21:44:25Z

pages/writing.md

+<!-- The VSCode is important to write in tandem with or after the Development environments part is written to avoid overlap. -->
+Most people develop Julia using a tool that allows for [interactive development](https://en.wikipedia.org/wiki/Interactive_programming).
+In VScode, you can [run code](https://www.julia-vscode.org/docs/stable/userguide/runningcode/) in the following useful ways:
+* For interactive development, the standard way to use Julia, you can use hotkeys to run selections, lines, sections, or whole files in the currently open REPL.


Not clear to a beginner what a hotkey is. Mention the universal shortcut Ctrl + Shift + P for the command pane?

I think hotkey is a common enough term that I feel comfortable using it. 3rd opinion?

That said, this part's not written yet.

FWIW, the Julia VSCode docs use the term "keyboard shortcuts".

gdalle · 2023-07-08T21:44:43Z

pages/writing.md

+This allows you to, among other things, load packages that improves your development experience or contain functionality that you use very often.
+
+It's tempting to put a lot of code in your `startup.jl` file for convenience's sake, but this convenience comes at a cost of increasing your startup time as it is executed.
+To balance convenience and time, we can use AST transformations to conditionally load functionality from packages only when necessary.


This is too scary for the first page

It's a hard dilemma. Conditional loading makes using Julia way better so I want to put it in, but I also hate introducing "magic code" in tutorials. I think conditional loading itself isn't that advanced, it's just not so common because the code itself isn't something most people can write themselves. The concept of "AST transformations" is advanced, I just put it in there to "remove the magic" for those who can understand it. That said, there's probably a better wording (or it can be a footnote) or we can just remove the conditional package loading part entirely.

Honestly with 1.9 / 1.10 it's no longer that expensive to pre-load small packages like BenchmarkTools, is it?

gdalle · 2023-07-08T21:44:57Z

pages/writing.md

+using Revise
+using OhMyREPL
+
+colorscheme!("GruvboxDark")


Is this from OhMyREPL?

I think so? Not sure lol

Yes, OhMyREPL ships a couple of color schemes: https://github.com/KristofferC/OhMyREPL.jl/blob/aa1d7e258f788dfb261ad070fb39657e9c9ab98a/src/passes/colorschemes.jl

gdalle · 2023-07-08T21:45:12Z

pages/writing.md

+colorscheme!("GruvboxDark")
+OhMyREPL.enable_pass!("RainbowBrackets", false)
+
+if Base.isinteractive() &&


I don't think this belongs on the first page, maybe as a footnote or linked file

In an effort to give a nearby example of everything but also not repeating myself too much I just put an actual config here. I think it's probably fine if we end up not putting the conditional loading part, then it's just a short code snippet that's also a genuinely useful startup.jl file.

We could add a folder in _assets with such typical files. I also wanna do one for runtests.jl

adrhill · 2023-07-10T09:31:20Z

pages/writing.md

+ENV["JULIA_EDITOR"] = "code"
+
+using Revise
+using OhMyREPL


Revise and OhMyREPL both recommend loading the packages in a try-catch statement:

https://timholy.github.io/Revise.jl/stable/config/#Using-Revise-by-default-1

try using Revise catch e @warn "Error initializing Revise" exception=(e, catch_backtrace()) end

https://kristofferc.github.io/OhMyREPL.jl/latest/installation/#Automatically-start-with-Julia.

atreplinit() do repl try @eval using OhMyREPL catch e @warn "error while importing OhMyREPL" e end end

adrhill · 2023-07-10T09:40:02Z

pages/writing.md

+```
+
+For unicode symbols, the query will return how to type the symbol in the REPL, which is useful when you copy-paste a symbol in without knowing its name, and fetch information about the object the symbol is bound to, just as above.
+


You could also mention that using help-mode with a string will call apropos and look for the string in all available docstrings:

help?> "determinant" LinearAlgebra.logabsdet LinearAlgebra.det LinearAlgebra.logdet LinearAlgebra.det_bareiss! LinearAlgebra.det_bareiss

This is quite useful to find / remember function names.

I did not know this...

adrhill · 2023-07-10T09:41:26Z

pages/writing.md

+For unicode symbols, the query will return how to type the symbol in the REPL, which is useful when you copy-paste a symbol in without knowing its name, and fetch information about the object the symbol is bound to, just as above.
+
+### Pkg mode (`]`)
+Pkg mode is for managing environments and packages that is based on the Rust package manager "cargo".


I think this sentence is missing a word.

(I'm also not sure the comparison to Rust's cargo is crucial enough to belong in the first sentence. This might confuse people who have no experience with Rust.)

gdalle · 2023-07-10T09:58:06Z

Just a word on reviewing: it's cool to spend time at the beginning to make sure that our general orientations and styles are aligned, but I don't expect this level of detail on all PRs :) Let's not discourage each other either, we can always re-modify after the fact

gdalle · 2023-07-11T11:40:53Z

@jacobusmmsmit I took your REPL content and merged it in #23 with the brand new Franklin REPL code blocks. Feel free to merge gdalle:main into your branch, remove duplicates and continue from there :)

* Test new REPL blocks * Re-test blocks * Fix CSS * Style help mode and more tests * Working and properly styled REPL section

jacobusmmsmit · 2023-07-11T17:39:11Z

Crap I just nuked my content.

jacobusmmsmit · 2023-07-11T17:46:59Z

made new branch RIP

First draft and comments.

4509316

jacobusmmsmit marked this pull request as draft June 23, 2023 12:45

gdalle reviewed Jun 23, 2023

View reviewed changes

jacobusmmsmit and others added 3 commits July 8, 2023 16:45

Add more detail about startup.jl and AST transform

88a3374

Merge branch 'main' into loading-and-running-draft

a9e0749

Add info about the REPL to Development environments section

93bbc38

jacobusmmsmit changed the title ~~First draft and comments.~~ Content for Development environments/Running code Jul 8, 2023

jacobusmmsmit marked this pull request as ready for review July 8, 2023 16:12

jacobusmmsmit commented Jul 8, 2023

View reviewed changes

pages/writing.md Outdated Show resolved Hide resolved

Remove comments in resolved conversations

6658f28

jacobusmmsmit mentioned this pull request Jul 8, 2023

Content for development environments and running code (redux) #21

Closed

gdalle reviewed Jul 8, 2023

View reviewed changes

adrhill reviewed Jul 10, 2023

View reviewed changes

gdalle mentioned this pull request Jul 11, 2023

Repl #23

Merged

gdalle added 2 commits July 11, 2023 19:33

Repl (#23)

d435ec3

* Test new REPL blocks * Re-test blocks * Fix CSS * Style help mode and more tests * Working and properly styled REPL section

Bump and lower bound Franklin version (#24)

2884f9b

jacobusmmsmit closed this Jul 11, 2023

jacobusmmsmit deleted the loading-and-running-draft branch July 11, 2023 17:45

		@@ -45,23 +45,131 @@ juliaup status

		## Development environments

		Depending on your experience and how you use Julia, some ways of writing code may be more familiar or useful to you than others.


		[^1]: Unless you're compiling binaries with [StaticTools.jl](https://github.com/brenhinkeller/StaticTools.jl).

		<!-- The VSCode is important to write in tandem with or after the Development environments part is written to avoid overlap. -->

		```

		For unicode symbols, the query will return how to type the symbol in the REPL, which is useful when you copy-paste a symbol in without knowing its name, and fetch information about the object the symbol is bound to, just as above.

Content for Development environments/Running code #3

Content for Development environments/Running code #3

Conversation

jacobusmmsmit commented Jun 23, 2023

jacobusmmsmit commented Jul 8, 2023

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

gdalle commented Jul 10, 2023

gdalle commented Jul 11, 2023 • edited Loading

jacobusmmsmit commented Jul 11, 2023

jacobusmmsmit commented Jul 11, 2023

gdalle commented Jul 11, 2023 •

edited

Loading