From 4eb0ef9e0fcef52b6cbbeca5d1f975afc834f2c2 Mon Sep 17 00:00:00 2001 From: singularitti Date: Tue, 24 Oct 2023 21:27:17 -0400 Subject: [PATCH] Remove EasyJobsBase/docs/ --- EasyJobsBase/docs/Project.toml | 4 - EasyJobsBase/docs/make.jl | 35 --- EasyJobsBase/docs/src/api.md | 52 ---- .../docs/src/developers/contributing.md | 262 ---------------- .../docs/src/developers/design-principles.md | 283 ------------------ .../docs/src/developers/style-guide.md | 59 ---- EasyJobsBase/docs/src/index.md | 76 ----- EasyJobsBase/docs/src/installation.md | 160 ---------- EasyJobsBase/docs/src/troubleshooting.md | 62 ---- 9 files changed, 993 deletions(-) delete mode 100644 EasyJobsBase/docs/Project.toml delete mode 100644 EasyJobsBase/docs/make.jl delete mode 100644 EasyJobsBase/docs/src/api.md delete mode 100644 EasyJobsBase/docs/src/developers/contributing.md delete mode 100644 EasyJobsBase/docs/src/developers/design-principles.md delete mode 100644 EasyJobsBase/docs/src/developers/style-guide.md delete mode 100644 EasyJobsBase/docs/src/index.md delete mode 100644 EasyJobsBase/docs/src/installation.md delete mode 100644 EasyJobsBase/docs/src/troubleshooting.md diff --git a/EasyJobsBase/docs/Project.toml b/EasyJobsBase/docs/Project.toml deleted file mode 100644 index 2a41421..0000000 --- a/EasyJobsBase/docs/Project.toml +++ /dev/null @@ -1,4 +0,0 @@ -[deps] -Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4" -EasyJobsBase = "db8ca866-b61f-4bd1-a9b9-75c107d645d4" -Thinkers = "6d80a3f9-a943-41fa-97b3-3004c0daf7a3" diff --git a/EasyJobsBase/docs/make.jl b/EasyJobsBase/docs/make.jl deleted file mode 100644 index 21fdcfe..0000000 --- a/EasyJobsBase/docs/make.jl +++ /dev/null @@ -1,35 +0,0 @@ -using EasyJobsBase -using Documenter - -DocMeta.setdocmeta!(EasyJobsBase, :DocTestSetup, :(using EasyJobsBase, Thinkers); recursive=true) - -makedocs(; - modules=[EasyJobsBase], - authors="singularitti and contributors", - repo="https://github.com/MineralsCloud/EasyJobsBase.jl/blob/{commit}{path}#{line}", - sitename="EasyJobsBase.jl", - format=Documenter.HTML(; - prettyurls=get(ENV, "CI", "false") == "true", - canonical="https://MineralsCloud.github.io/EasyJobsBase.jl", - edit_link="main", - assets=String[], - ), - pages=[ - "Home" => "index.md", - "Manual" => [ - "Installation guide" => "installation.md", - ], - "API Reference" => "api.md", - "Developer Docs" => [ - "Contributing" => "developers/contributing.md", - "Style Guide" => "developers/style-guide.md", - "Design Principles" => "developers/design-principles.md", - ], - "Troubleshooting" => "troubleshooting.md", - ], -) - -deploydocs(; - repo="github.com/MineralsCloud/EasyJobsBase.jl", - devbranch="main", -) diff --git a/EasyJobsBase/docs/src/api.md b/EasyJobsBase/docs/src/api.md deleted file mode 100644 index a5d5eb6..0000000 --- a/EasyJobsBase/docs/src/api.md +++ /dev/null @@ -1,52 +0,0 @@ -```@meta -CurrentModule = EasyJobsBase -``` - -# API Reference - -```@contents -Pages = ["api.md"] -Depth = 2 -``` - -## Public API - -```@docs -Job -chain! -→ -← -run! -execute! -getstatus -ispending -isrunning -isexited -issucceeded -isfailed -listpending -listrunning -listexited -listsucceeded -listfailed -countexecution -descriptionof -creationtimeof -starttimeof -endtimeof -timecostof -getresult -countparents -countchildren -``` - -## Private API - -The functions and types mentioned here are considered part of the private API and are not -intended for direct use by users. They may be modified, moved, or removed without notice and -are primarily meant for internal use within the package. Using them directly may result in -unexpected errors or compatibility issues in your code. - -```@docs -AsyncExecutor -``` diff --git a/EasyJobsBase/docs/src/developers/contributing.md b/EasyJobsBase/docs/src/developers/contributing.md deleted file mode 100644 index 4518d92..0000000 --- a/EasyJobsBase/docs/src/developers/contributing.md +++ /dev/null @@ -1,262 +0,0 @@ -# Contributing - -```@contents -Pages = ["contributing.md"] -Depth = 2 -``` - -Welcome! This document explains some ways you can contribute to EasyJobsBase. - -## Code of conduct - -This project and everyone participating in it is governed by the -[Contributor Covenant Code of Conduct](https://github.com/MineralsCloud/.github/blob/main/CODE_OF_CONDUCT.md). -By participating, you are expected to uphold this code. - -## Join the community forum - -First up, join the [community forum](https://github.com/MineralsCloud/EasyJobsBase.jl/discussions). - -The forum is a good place to ask questions about how to use EasyJobsBase. You can also -use the forum to discuss possible feature requests and bugs before raising a -GitHub issue (more on this below). - -Aside from asking questions, the easiest way you can contribute to EasyJobsBase is to -help answer questions on the forum! - -## Improve the documentation - -Chances are, if you asked (or answered) a question on the community forum, then -it is a sign that the [documentation](https://MineralsCloud.github.io/EasyJobsBase.jl/dev/) could be -improved. Moreover, since it is your question, you are probably the best-placed -person to improve it! - -The docs are written in Markdown and are built using -[Documenter.jl](https://github.com/JuliaDocs/Documenter.jl). -You can find the source of all the docs -[here](https://github.com/MineralsCloud/EasyJobsBase.jl/tree/main/docs). - -If your change is small (like fixing typos or one or two sentence corrections), -the easiest way to do this is via GitHub's online editor. (GitHub has -[help](https://help.github.com/articles/editing-files-in-another-user-s-repository/) -on how to do this.) - -If your change is larger or touches multiple files, you will need to make the -change locally and then use Git to submit a -[pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests). -(See [Contribute code to EasyJobsBase](@ref) below for more on this.) - -## File a bug report - -Another way to contribute to EasyJobsBase is to file -[bug reports](https://github.com/MineralsCloud/EasyJobsBase.jl/issues/new?template=bug_report.md). - -Make sure you read the info in the box where you write the body of the issue -before posting. You can also find a copy of that info -[here](https://github.com/MineralsCloud/EasyJobsBase.jl/blob/main/.github/ISSUE_TEMPLATE/bug_report.md). - -!!! tip - If you're unsure whether you have a real bug, post on the - [community forum](https://github.com/MineralsCloud/EasyJobsBase.jl/discussions) - first. Someone will either help you fix the problem or let you know the - most appropriate place to open a bug report. - -## Contribute code to EasyJobsBase - -Finally, you can also contribute code to EasyJobsBase! - -!!! warning - If you do not have experience with Git, GitHub, and Julia development, the - first steps can be a little daunting. However, there are lots of tutorials - available online, including: - - [GitHub](https://guides.github.com/activities/hello-world/) - - [Git and GitHub](https://try.github.io/) - - [Git](https://git-scm.com/book/en/v2) - - [Julia package development](https://docs.julialang.org/en/v1/stdlib/Pkg/#Developing-packages-1) - -Once you are familiar with Git and GitHub, the workflow for contributing code to -EasyJobsBase is similar to the following: - -### Step 1: decide what to work on - -The first step is to find an [open issue](https://github.com/MineralsCloud/EasyJobsBase.jl/issues) -(or open a new one) for the problem you want to solve. Then, _before_ spending -too much time on it, discuss what you are planning to do in the issue to see if -other contributors are fine with your proposed changes. Getting feedback early can -improve code quality and avoid time spent writing code that does not get merged into -EasyJobsBase. - -!!! tip - At this point, remember to be patient and polite; you may get a _lot_ of - comments on your issue! However, do not be afraid! Comments mean that people are - willing to help you improve the code that you are contributing to EasyJobsBase. - -### Step 2: fork EasyJobsBase - -Go to [https://github.com/MineralsCloud/EasyJobsBase.jl](https://github.com/MineralsCloud/EasyJobsBase.jl) -and click the "Fork" button in the top-right corner. This will create a copy of -EasyJobsBase under your GitHub account. - -### Step 3: install EasyJobsBase locally - -Similar to [Installation](@ref), open the Julia REPL and run: - -```@repl -using Pkg -Pkg.update() -Pkg.develop("EasyJobsBase") -``` - -Then the package will be cloned to your local machine. On *nix systems, the default path is -`~/.julia/dev/EasyJobsBase` unless you modify the -[`JULIA_DEPOT_PATH`](http://docs.julialang.org/en/v1/manual/environment-variables/#JULIA_DEPOT_PATH-1) -environment variable. If you're on -Windows, this will be `C:\\Users\\\\.julia\\dev\\EasyJobsBase`. -In the following text, we will call it `PKGROOT`. - -Go to `PKGROOT`, start a new Julia session, and run - -```@repl -using Pkg -Pkg.instantiate() -``` - -to instantiate the project. - -### Step 4: checkout a new branch - -!!! note - In the following, replace any instance of `GITHUB_ACCOUNT` with your GitHub - username. - -The next step is to check out a development branch. In a terminal (or command -prompt on Windows), run: - -```bash -cd ~/.julia/dev/EasyJobsBase - -git remote add GITHUB_ACCOUNT https://github.com/GITHUB_ACCOUNT/EasyJobsBase.jl.git - -git checkout main - -git pull - -git checkout -b my_new_branch -``` - -### Step 5: make changes - -Now make any changes to the source code inside the `~/.julia/dev/EasyJobsBase` -directory. - -Make sure you: - -- Follow our [Style Guide](@ref style) and [Run JuliaFormatter](@ref). -- Add tests and documentation for any changes or new features. - -!!! tip - When you change the source code, you'll need to restart Julia for the - changes to take effect. This is a pain, so install - [Revise.jl](https://github.com/timholy/Revise.jl). - -### Step 6a: test your code changes - -To test that your changes work, run the EasyJobsBase test-suite by opening Julia and -running: - -```julia-repl -julia> cd(joinpath(DEPOT_PATH[1], "dev", "EasyJobsBase")) - -julia> using Pkg - -julia> Pkg.activate(".") - Activating new project at `~/.julia/dev/EasyJobsBase` - -julia> Pkg.test() -``` - -!!! warning - Running the tests might take a long time. - -!!! tip - If you are using Revise.jl, you can also run the tests by calling `include`: - - ```julia-repl - include("test/runtests.jl") - ``` - - This can be faster if you want to re-run the tests multiple times. - -### Step 6b: test your documentation changes - -Open Julia, then run: - -```julia-repl -julia> cd(joinpath(DEPOT_PATH[1], "dev", "EasyJobsBase", "docs")) - -julia> using Pkg - -julia> Pkg.activate(".") - Activating new project at `~/.julia/dev/EasyJobsBase/docs` - -julia> include("src/make.jl") -``` - -After a while, a folder `PKGROOT/docs/build` will appear. Open -`PKGROOT/docs/build/index.html` with your favorite browser, and have fun! - -!!! warning - Building the documentation might take a long time. - -!!! tip - If there's a problem with the tests that you don't know how to fix, don't - worry. Continue to step 5, and one of the EasyJobsBase contributors will comment - on your pull request, telling you how to fix things. - -### Step 7: make a pull request - -Once you've made changes, you're ready to push the changes to GitHub. Run: - -```bash -cd ~/.julia/dev/EasyJobsBase - -git add . - -git commit -m "A descriptive message of the changes" - -git push -u GITHUB_ACCOUNT my_new_branch -``` - -Then go to [https://github.com/MineralsCloud/EasyJobsBase.jl/pulls](https://github.com/MineralsCloud/EasyJobsBase.jl/pulls) -and follow the instructions that pop up to open a pull request. - -### Step 8: respond to comments - -At this point, remember to be patient and polite; you may get a _lot_ of -comments on your pull request! However, do not be afraid! A lot of comments -means that people are willing to help you improve the code that you are -contributing to EasyJobsBase. - -To respond to the comments, go back to step 5, make any changes, test the -changes in step 6, and then make a new commit in step 7. Your PR will -automatically update. - -### Step 9: cleaning up - -Once the PR is merged, clean-up your Git repository, ready for the -next contribution! - -```bash -cd ~/.julia/dev/EasyJobsBase - -git checkout main - -git pull -``` - -!!! note - If you have suggestions to improve this guide, please make a pull request! - It's particularly helpful if you do this after your first pull request - because you'll know all the parts that could be explained better. - -Thanks for contributing to EasyJobsBase! diff --git a/EasyJobsBase/docs/src/developers/design-principles.md b/EasyJobsBase/docs/src/developers/design-principles.md deleted file mode 100644 index 5b2d917..0000000 --- a/EasyJobsBase/docs/src/developers/design-principles.md +++ /dev/null @@ -1,283 +0,0 @@ -# Design Principles - -```@contents -Pages = ["design-principles.md"] -Depth = 2 -``` - -We adopt some [`SciML`](https://sciml.ai/) design [guidelines](https://github.com/SciML/SciMLStyle) -here. Please read it before contributing! - -## Consistency vs adherence - -According to PEP8: - -> A style guide is about consistency. Consistency with this style guide is important. -> Consistency within a project is more important. Consistency within one module or function is the most important. -> -> However, know when to be inconsistent—sometimes style guide recommendations just aren't -> applicable. When in doubt, use your best judgment. Look at other examples and decide what -> looks best. And don’t hesitate to ask! - -## Community contribution guidelines - -For a comprehensive set of community contribution guidelines, refer to [ColPrac](https://github.com/SciML/ColPrac). -A relevant point to highlight PRs should do one thing. In the context of style, this means that PRs which update -the style of a package's code should not be mixed with fundamental code contributions. This separation makes it -easier to ensure that large style improvement are isolated from substantive (and potentially breaking) code changes. - -## Open source contributions are allowed to start small and grow over time - -If the standard for code contributions is that every PR needs to support every possible input type that anyone can -think of, the barrier would be too high for newcomers. Instead, the principle is to be as correct as possible to -begin with, and grow the generic support over time. All recommended functionality should be tested, any known -generality issues should be documented in an issue (and with a `@test_broken` test when possible). - -## Generic code is preferred unless code is known to be specific - -For example, the code: - -```@repl -function f(A, B) - for i in 1:length(A) - A[i] = A[i] + B[i] - end -end -``` - -would not be preferred for two reasons. One is that it assumes `A` uses one-based indexing, which would fail in cases -like [OffsetArrays](https://github.com/JuliaArrays/OffsetArrays.jl) and [FFTViews](https://github.com/JuliaArrays/FFTViews.jl). -Another issue is that it requires indexing, while not all array types support indexing (for example, -[CuArrays](https://github.com/JuliaGPU/CuArrays.jl)). A more generic compatible implementation of this function would be -to use broadcast, for example: - -```@repl -function f(A, B) - @. A = A + B -end -``` - -which would allow support for a wider variety of array types. - -## Internal types should match the types used by users when possible - -If `f(A)` takes the input of some collections and computes an output from those collections, then it should be -expected that if the user gives `A` as an `Array`, the computation should be done via `Array`s. If `A` was a -`CuArray`, then it should be expected that the computation should be internally done using a `CuArray` (or appropriately -error if not supported). For these reasons, constructing arrays via generic methods, like `similar(A)`, is preferred when -writing `f` instead of using non-generic constructors like `Array(undef,size(A))` unless the function is documented as -being non-generic. - -## Trait definition and adherence to generic interface is preferred when possible - -Julia provides many interfaces, for example: - -- [Iteration](https://docs.julialang.org/en/v1/manual/interfaces/#man-interface-iteration) -- [Indexing](https://docs.julialang.org/en/v1/manual/interfaces/#Indexing) -- [Broadcast](https://docs.julialang.org/en/v1/manual/interfaces/#man-interfaces-broadcasting) - -Those interfaces should be followed when possible. For example, when defining broadcast overloads, -one should implement a `BroadcastStyle` as suggested by the documentation instead of simply attempting -to bypass the broadcast system via `copyto!` overloads. - -When interface functions are missing, these should be added to Base Julia or an interface package, -like [ArrayInterface.jl](https://github.com/JuliaArrays/ArrayInterface.jl). Such traits should be -declared and used when appropriate. For example, if a line of code requires mutation, the trait -`ArrayInterface.ismutable(A)` should be checked before attempting to mutate, and informative error -messages should be written to capture the immutable case (or, an alternative code which does not -mutate should be given). - -One example of this principle is demonstrated in the generation of Jacobian matrices. In many scientific -applications, one may wish to generate a Jacobian cache from the user's input `u0`. A naive way to generate -this Jacobian is `J = similar(u0,length(u0),length(u0))`. However, this will generate a Jacobian `J` such -that `J isa Matrix`. - -## Macros should be limited and only be used for syntactic sugar - -Macros define new syntax, and for this reason they tend to be less composable than other coding styles -and require prior familiarity to be easily understood. One principle to keep in mind is, "can the person -reading the code easily picture what code is being generated?". For example, a user of Soss.jl may not know -what code is being generated by: - -```julia -@model (x, α) begin - σ ~ Exponential() - β ~ Normal() - y ~ For(x) do xj - Normal(α + β * xj, σ) - end - return y -end -``` - -and thus using such a macro as the interface is not preferred when possible. However, a macro like -[`@muladd`](https://github.com/SciML/MuladdMacro.jl) is trivial to picture on a code (it recursively -transforms `a*b + c` to `muladd(a,b,c)` for more -[accuracy and efficiency](https://en.wikipedia.org/wiki/Multiply%E2%80%93accumulate_operation)), so using -such a macro for example: - -```julia -julia> @macroexpand(@muladd k3 = f(t + c3 * dt, @. uprev + dt * (a031 * k1 + a032 * k2))) -:(k3 = f((muladd)(c3, dt, t), (muladd).(dt, (muladd).(a032, k2, (*).(a031, k1)), uprev))) -``` - -is recommended. Some macros in this category are: - -- `@inbounds` -- [`@muladd`](https://github.com/SciML/MuladdMacro.jl) -- `@view` -- [`@named`](https://github.com/SciML/ModelingToolkit.jl) -- `@.` -- [`@..`](https://github.com/YingboMa/FastBroadcast.jl) - -Some performance macros, like `@simd`, `@threads`, or -[`@turbo` from LoopVectorization.jl](https://github.com/JuliaSIMD/LoopVectorization.jl), -make an exception in that their generated code may be foreign to many users. However, they still are -classified as appropriate uses as they are syntactic sugar since they do (or should) not change the behavior -of the program in measurable ways other than performance. - -## Errors should be caught as high as possible, and error messages should be contextualized for newcomers - -Whenever possible, defensive programming should be used to check for potential errors before they are encountered -deeper within a package. For example, if one knows that `f(u0,p)` will error unless `u0` is the size of `p`, this -should be caught at the start of the function to throw a domain specific error, for example "parameters and initial -condition should be the same size". - -## Subpackaging and interface packages is preferred over conditional modules via Requires.jl - -Requires.jl should be avoided at all costs. If an interface package exists, such as -[ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) for defining automatic differentiation -rules without requiring a dependency on the whole ChainRules.jl system, or -[RecipesBase.jl](https://github.com/JuliaPlots/RecipesBase.jl) which allows for defining Plots.jl -plot recipes without a dependency on Plots.jl, a direct dependency on these interface packages is -preferred. - -Otherwise, instead of resorting to a conditional dependency using Requires.jl, it is -preferred one creates subpackages, i.e. smaller independent packages kept within the same Github repository -with independent versioning and package management. An example of this is seen in -[Optimization.jl](https://github.com/SciML/Optimization.jl) which has subpackages like -[OptimizationBBO.jl](https://github.com/SciML/Optimization.jl/tree/master/lib/OptimizationBBO) for -BlackBoxOptim.jl support. - -Some important interface packages to know about are: - -- [ChainRulesCore.jl](https://github.com/JuliaDiff/ChainRulesCore.jl) -- [RecipesBase.jl](https://github.com/JuliaPlots/RecipesBase.jl) -- [ArrayInterface.jl](https://github.com/JuliaArrays/ArrayInterface.jl) -- [CommonSolve.jl](https://github.com/SciML/CommonSolve.jl) -- [SciMLBase.jl](https://github.com/SciML/SciMLBase.jl) - -## Functions should either attempt to be non-allocating and reuse caches, or treat inputs as immutable - -Mutating codes and non-mutating codes fall into different worlds. When a code is fully immutable, -the compiler can better reason about dependencies, optimize the code, and check for correctness. -However, many times a code making the fullest use of mutation can outperform even what the best compilers -of today can generate. That said, the worst of all worlds is when code mixes mutation with non-mutating -code. Not only is this a mishmash of coding styles, it has the potential non-locality and compiler -proof issues of mutating code while not fully benefiting from the mutation. - -## Out-of-place and immutability is preferred when sufficient performant - -Mutation is used to get more performance by decreasing the amount of heap allocations. However, -if it's not helpful for heap allocations in a given spot, do not use mutation. Mutation is scary -and should be avoided unless it gives an immediate benefit. For example, if -matrices are sufficiently large, then `A*B` is as fast as `mul!(C,A,B)`, and thus writing -`A*B` is preferred (unless the rest of the function is being careful about being fully non-allocating, -in which case this should be `mul!` for consistency). - -Similarly, when defining types, using `struct` is preferred to `mutable struct` unless mutating -the struct is a common occurrence. Even if mutating the struct is a common occurrence, see whether -using [Setfield.jl](https://github.com/jw3126/Setfield.jl) is sufficient. The compiler will optimize -the construction of immutable structs, and thus this can be more efficient if it's not too much of a -code hassle. - -## Tests should attempt to cover a wide gamut of input types - -Code coverage numbers are meaningless if one does not consider the input types. For example, one can -hit all the code with `Array`, but that does not test whether `CuArray` is compatible! Thus, it's -always good to think of coverage not in terms of lines of code but in terms of type coverage. A good -list of number types to think about are: - -- `Float64` -- `Float32` -- `Complex` -- [`Dual`](https://github.com/JuliaDiff/ForwardDiff.jl) -- `BigFloat` - -Array types to think about testing are: - -- `Array` -- [`OffsetArray`](https://github.com/JuliaArrays/OffsetArrays.jl) -- [`CuArray`](https://github.com/JuliaGPU/CUDA.jl) - -## When in doubt, a submodule should become a subpackage or separate package - -Keep packages to one core idea. If there's something separate enough to be a submodule, could it -instead be a separate well-tested and documented package to be used by other packages? Most likely -yes. - -## Globals should be avoided whenever possible - -Global variables should be avoided whenever possible. When required, global variables should be -constants and have an all uppercase name separated with underscores (e.g. `MY_CONSTANT`). They should be -defined at the top of the file, immediately after imports and exports but before an `__init__` function. -If you truly want mutable global style behavior you may want to look into mutable containers. - -## Type-stable and type-grounded code is preferred wherever possible - -Type-stable and type-grounded code helps the compiler create not only more optimized code, but also -faster to compile code. Always keep containers well-typed, functions specializing on the appropriate -arguments, and types concrete. - -## Closures should be avoided whenever possible - -Closures can cause accidental type instabilities that are difficult to track down and debug; in the -long run it saves time to always program defensively and avoid writing closures in the first place, -even when a particular closure would not have been problematic. A similar argument applies to reading -code with closures; if someone is looking for type instabilities, this is faster to do when code does -not contain closures. -See examples [here](https://discourse.julialang.org/t/are-closures-should-be-avoided-whenever-possible-still-valid-in-julia-v1-9/95893/5). - -Furthermore, if you want to update variables in an outer scope, do so explicitly with `Ref`s or self -defined structs. - -## Numerical functionality should use the appropriate generic numerical interfaces - -While you can use `A\b` to do a linear solve inside a package, that does not mean that you should. -This interface is only sufficient for performing factorizations, and so that limits the scaling -choices, the types of `A` that can be supported, etc. Instead, linear solves within packages should -use LinearSolve.jl. Similarly, nonlinear solves should use NonlinearSolve.jl. Optimization should use -Optimization.jl. Etc. This allows the full generic choice to be given to the user without depending -on every solver package (effectively recreating the generic interfaces within each package). - -## Functions should capture one underlying principle - -Functions mean one thing. Every dispatch of `+` should be "the meaning of addition on these types". -While in theory you could add dispatches to `+` that mean something different, that will fail in -generic code for which `+` means addition. Thus, for generic code to work, code needs to adhere to -one meaning for each function. Every dispatch should be an instantiation of that meaning. - -## Internal choices should be exposed as options whenever possible - -Whenever possible, numerical values and choices within scripts should be exposed as options -to the user. This promotes code reusability beyond the few cases the author may have expected. - -## Prefer code reuse over rewrites whenever possible - -If a package has a function you need, use the package. Add a dependency if you need to. If the -function is missing a feature, prefer to add that feature to said package and then add it as a -dependency. If the dependency is potentially troublesome, for example because it has a high -load time, prefer to spend time helping said package fix these issues and add the dependency. -Only when it does not seem possible to make the package "good enough" should using the package -be abandoned. If it is abandoned, consider building a new package for this functionality as you -need it, and then make it a dependency. - -## Prefer to not shadow functions - -Two functions can have the same name in Julia by having different namespaces. For example, -`X.f` and `Y.f` can be two different functions, with different dispatches, but the same name. -This should be avoided whenever possible. Instead of creating `MyPackage.sort`, consider -adding dispatches to `Base.sort` for your types if these new dispatches match the underlying -principle of the function. If it doesn't, prefer to use a different name. While using `MyPackage.sort` -is not conflicting, it is going to be confusing for most people unfamiliar with your code, -so `MyPackage.special_sort` would be more helpful to newcomers reading the code. diff --git a/EasyJobsBase/docs/src/developers/style-guide.md b/EasyJobsBase/docs/src/developers/style-guide.md deleted file mode 100644 index e461de0..0000000 --- a/EasyJobsBase/docs/src/developers/style-guide.md +++ /dev/null @@ -1,59 +0,0 @@ -# [Style Guide](@id style) - -This section describes the coding style rules that apply to our code and that -we recommend you to use it also. - -In some cases, our style guide diverges from Julia's official -[Style Guide](https://docs.julialang.org/en/v1/manual/style-guide/) (Please read it!). -All such cases will be explicitly noted and justified. - -Our style guide adopts many recommendations from the -[BlueStyle](https://github.com/invenia/BlueStyle). -Please read the [BlueStyle](https://github.com/invenia/BlueStyle) -before contributing to this package. -If not following, your pull requests may not be accepted. - -!!! info - The style guide is always a work in progress, and not all EasyJobsBase code - follows the rules. When modifying EasyJobsBase, please fix the style violations - of the surrounding code (i.e., leave the code tidier than when you - started). If large changes are needed, consider separating them into - another pull request. - -## Formatting - -### Run JuliaFormatter - -EasyJobsBase uses [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl) as -an auto-formatting tool. - -We use the options contained in [`.JuliaFormatter.toml`](https://github.com/MineralsCloud/EasyJobsBase.jl/blob/main/.JuliaFormatter.toml). - -To format your code, `cd` to the EasyJobsBase directory, then run: - -```@repl -using Pkg -Pkg.add("JuliaFormatter") -using JuliaFormatter: format -format("docs") -format("src") -format("test") -``` - -!!! info - A continuous integration check verifies that all PRs made to EasyJobsBase have - passed the formatter. - -The following sections outline extra style guide points that are not fixed -automatically by JuliaFormatter. - -### Use the Julia extension for Visual Studio Code - -Please use [Visual Studio Code](https://code.visualstudio.com/) with the -[Julia extension](https://marketplace.visualstudio.com/items?itemName=julialang.language-julia) -to edit, format, and test your code. -We do not recommend using other editors to edit your code for the time being. - -This extension already has [JuliaFormatter](https://github.com/domluna/JuliaFormatter.jl) -integrated. So to format your code, follow the steps listed -[here](https://www.julia-vscode.org/docs/stable/userguide/formatter/). diff --git a/EasyJobsBase/docs/src/index.md b/EasyJobsBase/docs/src/index.md deleted file mode 100644 index c31535b..0000000 --- a/EasyJobsBase/docs/src/index.md +++ /dev/null @@ -1,76 +0,0 @@ -```@meta -CurrentModule = EasyJobsBase -``` - -# EasyJobsBase - -Documentation for [EasyJobsBase](https://github.com/MineralsCloud/EasyJobsBase.jl). - -See the [Index](@ref main-index) for the complete list of documented functions -and types. - -The code is [hosted on GitHub](https://github.com/MineralsCloud/EasyJobsBase.jl), -with some continuous integration services to test its validity. - -This repository is created and maintained by [@singularitti](https://github.com/singularitti). -You are very welcome to contribute. - -## Installation - -The package can be installed with the Julia package manager. -From the Julia REPL, type `]` to enter the Pkg REPL mode and run: - -```julia -pkg> add EasyJobsBase -``` - -Or, equivalently, via the `Pkg` API: - -```@repl -import Pkg; Pkg.add("EasyJobsBase") -``` - -## Documentation - -- [**STABLE**](https://MineralsCloud.github.io/EasyJobsBase.jl/stable) — **documentation of the most recently tagged version.** -- [**DEV**](https://MineralsCloud.github.io/EasyJobsBase.jl/dev) — _documentation of the in-development version._ - -## Project status - -The package is tested against, and being developed for, Julia `1.6` and above on Linux, -macOS, and Windows. - -## Questions and contributions - -Usage questions can be posted on -[our discussion page](https://github.com/MineralsCloud/EasyJobsBase.jl/discussions). - -Contributions are very welcome, as are feature requests and suggestions. Please open an -[issue](https://github.com/MineralsCloud/EasyJobsBase.jl/issues) -if you encounter any problems. The [Contributing](@ref) page has -a few guidelines that should be followed when opening pull requests and contributing code. - -## Manual outline - -```@contents -Pages = [ - "installation.md", - "developers/contributing.md", - "developers/style-guide.md", - "developers/design-principles.md", - "troubleshooting.md", -] -Depth = 3 -``` - -## Library outline - -```@contents -Pages = ["api.md"] -``` - -### [Index](@id main-index) - -```@index -Pages = ["api.md"] -``` diff --git a/EasyJobsBase/docs/src/installation.md b/EasyJobsBase/docs/src/installation.md deleted file mode 100644 index 6a36a46..0000000 --- a/EasyJobsBase/docs/src/installation.md +++ /dev/null @@ -1,160 +0,0 @@ -# [Installation Guide](@id installation) - -```@contents -Pages = ["installation.md"] -Depth = 2 -``` - -Here are the installation instructions for package -[EasyJobsBase](https://github.com/MineralsCloud/EasyJobsBase.jl). -If you have trouble installing it, please refer to our [Troubleshooting](@ref) page -for more information. - -## Install Julia - -First, you should install [Julia](https://julialang.org/). We recommend downloading it from -[its official website](https://julialang.org/downloads/). Please follow the detailed -instructions on its website if you have to -[build Julia from source](https://docs.julialang.org/en/v1/devdocs/build/build/). -Some computing centers provide preinstalled Julia. Please contact your administrator for -more information in that case. -Here's some additional information on -[how to set up Julia on HPC systems](https://github.com/hlrs-tasc/julia-on-hpc-systems). - -If you have [Homebrew](https://brew.sh) installed, -[open `Terminal.app`](https://support.apple.com/guide/terminal/open-or-quit-terminal-apd5265185d-f365-44cb-8b09-71a064a42125/mac) -and type - -```bash -brew install julia -``` - -to install it as a [formula](https://docs.brew.sh/Formula-Cookbook). - -If you are also using macOS and want to install it as a prebuilt binary app, type - -```bash -brew install --cask julia -``` - -instead. - -If you want to install multiple Julia versions in the same operating system, -a recommended way is to use a version manager such as -[`juliaup`](https://github.com/JuliaLang/juliaup). -First, [install `juliaup`](https://github.com/JuliaLang/juliaup#installation). -Then, run - -```bash -juliaup add release -juliaup default release -``` - -to configure the `julia` command to start the latest stable version of -Julia (this is also the default value). - -There is a [short video introduction to `juliaup`](https://youtu.be/14zfdbzq5BM) -made by its authors. - -### Which version should I pick? - -You can install the "Current stable release" or the "Long-term support (LTS) -release". - -- The "Current stable release" is the latest release of Julia. It has access to - newer features, and is likely faster. -- The "Long-term support release" is an older version of Julia that has - continued to receive bug and security fixes. However, it may not have the - latest features or performance improvements. - -For most users, you should install the "Current stable release", and whenever -Julia releases a new version of the current stable release, you should update -your version of Julia. Note that any code you write on one version of the -current stable release will continue to work on all subsequent releases. - -For users in restricted software environments (e.g., your enterprise IT controls -what software you can install), you may be better off installing the long-term -support release because you will not have to update Julia as frequently. - -Versions higher than `v1.3`, -especially `v1.6`, are strongly recommended. This package may not work on `v1.0` and below. -Since the Julia team has set `v1.6` as the LTS release, -we will gradually drop support for versions below `v1.6`. - -Julia and Julia packages support multiple operating systems and CPU architectures; check -[this table](https://julialang.org/downloads/#supported_platforms) to see if it can be -installed on your machine. For Mac computers with M-series processors, this package and its -dependencies may not work. Please install the Intel-compatible version of Julia (for macOS -x86-64) if any platform-related error occurs. - -## Install EasyJobsBase - -Now I am using [macOS](https://en.wikipedia.org/wiki/MacOS) as a standard -platform to explain the following steps: - -1. Open `Terminal.app`, and type `julia` to start an interactive session (known as the - [REPL](https://docs.julialang.org/en/v1/stdlib/REPL/)). - -2. Run the following commands and wait for them to finish: - - ```julia-repl - julia> using Pkg - - julia> Pkg.update() - - julia> Pkg.add("EasyJobsBase") - ``` - -3. Run - - ```julia-repl - julia> using EasyJobsBase - ``` - - and have fun! - -4. While using, please keep this Julia session alive. Restarting might cost some time. - -If you want to install the latest in-development (probably buggy) -version of EasyJobsBase, type - -```@repl -using Pkg -Pkg.update() -pkg"add https://github.com/MineralsCloud/EasyJobsBase.jl" -``` - -in the second step above. - -## Update EasyJobsBase - -Please [watch](https://docs.github.com/en/account-and-profile/managing-subscriptions-and-notifications-on-github/setting-up-notifications/configuring-notifications#configuring-your-watch-settings-for-an-individual-repository) -our [GitHub repository](https://github.com/MineralsCloud/EasyJobsBase.jl) -for new releases. -Once we release a new version, you can update EasyJobsBase by typing - -```@repl -using Pkg -Pkg.update("EasyJobsBase") -Pkg.gc() -``` - -in the Julia REPL. - -## Uninstall and reinstall EasyJobsBase - -Sometimes errors may occur if the package is not properly installed. -In this case, you may want to uninstall and reinstall the package. Here is how to do that: - -1. To uninstall, in a Julia session, run - - ```julia-repl - julia> using Pkg - - julia> Pkg.rm("EasyJobsBase") - - julia> Pkg.gc() - ``` - -2. Press `ctrl+d` to quit the current session. Start a new Julia session and - reinstall EasyJobsBase. diff --git a/EasyJobsBase/docs/src/troubleshooting.md b/EasyJobsBase/docs/src/troubleshooting.md deleted file mode 100644 index ab9b78d..0000000 --- a/EasyJobsBase/docs/src/troubleshooting.md +++ /dev/null @@ -1,62 +0,0 @@ -# Troubleshooting - -```@contents -Pages = ["troubleshooting.md"] -Depth = 2 -``` - -This page collects some possible errors you may encounter and trick how to fix them. -If you have some questions about how to use this code, you are welcome to -[discuss with us](https://github.com/MineralsCloud/EasyJobsBase.jl/discussions). - -If you have additional tips, please either -[report an issue](https://github.com/MineralsCloud/EasyJobsBase.jl/issues/new) or -[submit a PR](https://github.com/MineralsCloud/EasyJobsBase.jl/compare) with suggestions. - -## Installation problems - -### Cannot find the `julia` executable - -Make sure you have Julia installed in your environment. Please download the latest -[stable version](https://julialang.org/downloads/#current_stable_release) for your platform. -If you are using a *nix system, the recommended way is to use -[Juliaup](https://github.com/JuliaLang/juliaup). If you do not want to install Juliaup -or you are using other platforms that Julia supports, download the corresponding binaries. -Then, create a symbolic link to the Julia executable. If the path is not in your `$PATH` -environment variable, export it to your `$PATH`. - -Some clusters, like -[Habanero](https://confluence.columbia.edu/confluence/display/rcs/Habanero+HPC+Cluster+User+Documentation), -[Comet](https://www.sdsc.edu/support/user_guides/comet.html), -or [Expanse](https://www.sdsc.edu/services/hpc/expanse/index.html), -already have Julia installed as a module, you may -just `module load julia` to use it. If not, either install by yourself or contact your -administrator. - -## Loading EasyJobsBase - -### Julia compiles/loads slow - -First, we recommend you download the latest version of Julia. Usually, the newest version -has the best performance. - -If you just want Julia to do a simple task and only once, you could start the Julia REPL with - -```bash -julia --compile=min -``` - -to minimize compilation or - -```bash -julia --optimize=0 -``` - -to minimize optimizations, or just use both. Or you could make a system image -and run with - -```bash -julia --sysimage custom-image.so -``` - -See [Fredrik Ekre's talk](https://youtu.be/IuwxE3m0_QQ?t=313) for details.