Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

README example is excessively large + README needs updating for current julia REPL look #961

Closed
glwagner opened this issue Sep 18, 2020 · 13 comments
Labels
good first issue 🐤 Let us know if you're interested in working on this! help wanted 🦮 plz halp (guide dog provided)

Comments

@glwagner
Copy link
Member

The README example builds a grid of size (100, 100, 50), which is non-small. We should make the intro example more bite-size.

@navidcy
Copy link
Collaborator

navidcy commented Sep 21, 2020

my 2 cents: It's a bit "tricky" to have code in the README since with constant code upgrades oftentimes the README code gets outdated...

@glwagner
Copy link
Member Author

my 2 cents: It's a bit "tricky" to have code in the README since with constant code upgrades oftentimes the README code gets outdated...

That's true, probably best not to have too much. I personally find code in the README to be super helpful for "quick starting" though...

@navidcy
Copy link
Collaborator

navidcy commented Sep 22, 2020

Actually me too!
(unless it's broken)

@glwagner
Copy link
Member Author

Actually, it probably wouldn't be that hard to run code in the README in a test. Somebody should write a package for that.

@ali-ramadhan
Copy link
Member

ali-ramadhan commented Sep 22, 2020

Could do something like

using Markdown
readme = Markdown.parse(read("README.md", String))
julia_code_snippets = filter(c -> c isa Markdown.Code && c.language == "julia", readme.content)
for code_snippet in julia_code_snippets
    # Need begin and end in case code snippet is multi-line.
    Meta.parse("begin $(code_snippet.code) end") |> eval
end

but then the code blocks under "Installation instructions" should not be julia code blocks.

@glwagner
Copy link
Member Author

glwagner commented Sep 22, 2020

but then the code blocks under "Installation instructions" should not be julia code blocks.

That's ok for me... we really want "julia-repl" highlighting for those blocks anyways.

Or, we can further-filter the lines that start with julia> ?

@glwagner
Copy link
Member Author

It doesn't actually help to ask for julia syntax highlighting in the installation instructions anyways:

image

@glwagner
Copy link
Member Author

glwagner commented Sep 22, 2020

What it looks like for me:

image

In fact, a screenshot rather than code could make more sense ? (Note that its also out of date with how the current julia REPL / package manager looks)

@glwagner
Copy link
Member Author

Actually wondering if we should provide code that installs julia:

using Pkg
Pkg.add("Oceananigans")
Pkg.instantiate()

Then people can copy paste like they really want to.

If they know how to use the package manager, they already know what to do (or we can add a separate comment for such people).

@glwagner glwagner changed the title README example is excessively large README example is excessively large + README needs updating Sep 22, 2020
@glwagner glwagner changed the title README example is excessively large + README needs updating README example is excessively large + README needs updating for current julia REPL look Sep 22, 2020
@ali-ramadhan
Copy link
Member

Hmmm, yeah copy-pastable code for installation might be better. Would rather use package mode but the benefit of being to copy paste is pretty sweet.

@glwagner
Copy link
Member Author

We could use something like

Julia's package manager will happily install the latest version of Oceananigans for you:

using Pkg
Pkg.add("Oceananigans")
Pkg.instantiate()

Alternatively, you can press ] from Julia's REPL to enter package manager mode and type pkg> add Oceananigans followed by pkg> instantiate. We recommend installing Oceananigans with the built-in Julia package manager, because this installs a stable, tagged release.

@glwagner
Copy link
Member Author

Another README issue: we should change

It is designed to solve the rotating Boussinesq equations...

to

It solves the rotating Boussinesq equations...

@ali-ramadhan ali-ramadhan added good first issue 🐤 Let us know if you're interested in working on this! help wanted 🦮 plz halp (guide dog provided) labels Oct 1, 2020
@glwagner
Copy link
Member Author

I'm closing this issue because I'm judging that it's not of current, timely relevance to Oceananigans development. If you would like to make it a higher priority or if you think the issue was closed in error please feel free to re-open.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
good first issue 🐤 Let us know if you're interested in working on this! help wanted 🦮 plz halp (guide dog provided)
Projects
None yet
Development

No branches or pull requests

3 participants