Update readme and docs

README.md

@@ -1,24 +1,65 @@
-# LorentzVectorBase
-
-Base interfaces for four-momenta in high-energy physics.
+# LorentzVectorBase.jl
 
 [![Stable Documentation](https://img.shields.io/badge/docs-stable-blue.svg)](https://JuliaHEP.github.io/LorentzVectorBase.jl/stable/)
 [![In development documentation](https://img.shields.io/badge/docs-dev-blue.svg)](https://JuliaHEP.github.io/LorentzVectorBase.jl/dev/)
 [![Test workflow status](https://github.com/JuliaHEP/LorentzVectorBase.jl/actions/workflows/Test.yml/badge.svg?branch=main)](https://github.com/JuliaHEP/LorentzVectorBase.jl/actions/workflows/Test.yml?query=branch%3Amain)
 [![Docs workflow Status](https://github.com/JuliaHEP/LorentzVectorBase.jl/actions/workflows/Docs.yml/badge.svg?branch=main)](https://github.com/JuliaHEP/LorentzVectorBase.jl/actions/workflows/Docs.yml?query=branch%3Amain)
 [![Coverage](https://codecov.io/gh/JuliaHEP/LorentzVectorBase.jl/branch/main/graph/badge.svg)](https://codecov.io/gh/JuliaHEP/LorentzVectorBase.jl)
 
-# Code Formatting
+**LorentzVectorBase.jl** provides base interfaces for four-momenta in high-energy physics, facilitating standardized representations and operations on Lorentz vectors.
+
+## Installation
+
+Install the package using Julia's package manager:
+
+```julia
+using Pkg
+Pkg.add("LorentzVectorBase")
+```
+
+Alternatively, in the Julia REPL, enter `pkg>` mode by typing `]`, then
+
+```julia-repl
+add LorentzVectorBase
+```
+
+## Usage
+
+This package defines abstract interfaces for Lorentz vectors. To utilize concrete implementations, consider packages like [LorentzVectorHEP.jl](https://github.com/JuliaHEP/LorentzVectorHEP.jl) or [FourVectors.jl](https://github.com/mmikhasenko/FourVectors.jl).
 
-This package follows a standardized formatting configuration to ensure consistency across
-the codebase. We enforce these formatting guidelines by running checks on all pull requests
-through continuous integration (CI).
+## Example
 
-To format your code locally and ensure it meets the required standards, you can run the
-following command in your terminal:
+Here is an example of how to define a custom Lorentz vector type and implement the required interface functions:
 
-```bash
+```Julia
+struct CustomLVector
+  x
+  y
+  z
+  t
+end
+
+LorentzVectorBase.coordinate_system(::CustomLVector) = LorentzVectorBase.XYZT()
+LorentzVectorBase.x(lv::CustomLVector) = lv.x
+LorentzVectorBase.y(lv::CustomLVector) = lv.y
+LorentzVectorBase.z(lv::CustomLVector) = lv.z
+LorentzVectorBase.t(lv::CustomLVector) = lv.t
+
+
+c = CustomLVector(1,2,3,4)
+@assert isapprox(LorentzVectorBase.spatial_magnitude(c), sqrt(1^2 + 2^2 + 3^2))
+```
+
+## Code Formatting
+
+To maintain code consistency, format your code with:
+
+```julia
 julia --project=.formatting -e 'using Pkg; Pkg.instantiate(); include(".formatting/format_all.jl")'
 ```
 
-This will apply the necessary formatting rules to your code before submission.
+This ensures adherence to the project's formatting standards.
+
+## License
+
+This project is licensed under the MIT License.

docs/Project.toml

@@ -1,3 +1,4 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 LorentzVectorBase = "592a752d-6533-4762-a71b-738712ea30ec"

docs/make.jl

@@ -7,28 +7,81 @@ Pkg.develop(; path=project_path)
 
 using LorentzVectorBase
 using Documenter
+using Literate
 
 DocMeta.setdocmeta!(
   LorentzVectorBase, :DocTestSetup, :(using LorentzVectorBase); recursive=true
 )
 
+# some paths for links
+readme_path = joinpath(project_path, "README.md")
+index_path = joinpath(project_path, "docs/src/index.md")
+license_path = "https://github.com/QEDjl-project/QEDcore.jl/blob/main/LICENSE"
+
+# Copy README.md from the project base folder and use it as the start page
+open(readme_path, "r") do readme_in
+  readme_string = read(readme_in, String)
+
+  # replace relative links in the README.md
+  readme_string = replace(readme_string, "[MIT](LICENSE)" => "[MIT]($(license_path))")
+
+  open(index_path, "w") do readme_out
+    write(readme_out, readme_string)
+  end
+end
+
+# setup examples using Literate.jl
+literate_paths = [
+  Base.Filesystem.joinpath(project_path, "docs/src/tutorial/20-new_four_vector.jl"),
+  Base.Filesystem.joinpath(project_path, "docs/src/tutorial/21-new_coord_system.jl"),
+]
+
+tutorial_output_dir = joinpath(project_path, "docs/src/generated/")
+!ispath(tutorial_output_dir) && mkdir(tutorial_output_dir)
+@info "Literate: create temp dir at $tutorial_output_dir"
+
+tutorial_output_dir_name = splitpath(tutorial_output_dir)[end]
+
 pages = [
-  "Home" => "index.md", "Interface" => "10-interface.md", "Reference" => "95-reference.md"
+  "Home" => "index.md",
+  "Interface" => "10-interface.md",
+  "Tutorial" => [
+    "New Four-Vector" => joinpath(tutorial_output_dir_name, "20-new_four_vector.md"),
+    "New Coordinate System" =>
+      joinpath(tutorial_output_dir_name, "21-new_coord_system.md"),
+  ],
+  "Contributors guide" => "90-contributing.md",
+  "Developer docs" => "91-dev_docs.md",
+  "API Reference" => "95-reference.md",
 ]
 
-makedocs(;
-  modules=[LorentzVectorBase],
-  authors="Uwe Hernandez Acosta <[email protected]>",
-  repo=Documenter.Remotes.GitHub("JuliaHEP", "LorentzVectorBase.jl"),
-  sitename="LorentzVectorBase.jl",
-  format=Documenter.HTML(;
-    prettyurls=get(ENV, "CI", "false") == "true",
-    canonical="https://JuliaHEP.github.io/LorentzVectorBase.jl",
-    # repolink="https://github.com/JuliaHEP/LorentzVectorBase.jl",
-    # edit_link="main",
-    assets=String[],
-  ),
-  pages=pages,
-)
+try
+
+  # generate markdown files with Literate.jl
+  for file in literate_paths
+    Literate.markdown(file, tutorial_output_dir; documenter=true)
+  end
+  makedocs(;
+    modules=[LorentzVectorBase],
+    authors="Uwe Hernandez Acosta <[email protected]>",
+    repo=Documenter.Remotes.GitHub("JuliaHEP", "LorentzVectorBase.jl"),
+    sitename="LorentzVectorBase.jl",
+    format=Documenter.HTML(;
+      prettyurls=get(ENV, "CI", "false") == "true",
+      canonical="https://JuliaHEP.github.io/LorentzVectorBase.jl",
+      # repolink="https://github.com/JuliaHEP/LorentzVectorBase.jl",
+      # edit_link="main",
+      assets=String[],
+    ),
+    pages=pages,
+  )
+
+  deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl", push_preview=true)
+finally
+  # doing some garbage collection
+  @info "GarbageCollection: remove generated landing page"
+  rm(index_path)
 
-deploydocs(; repo="github.com/JuliaHEP/LorentzVectorBase.jl", push_preview=true)
+  @info "GarbageCollection: remove generated tutorial files"
+  rm(tutorial_output_dir; recursive=true)
+end