Documentation and Manuals (#69)

In the same spirit as the respective [QEDbase PR](QEDjl-project/QEDbase.jl#127), this adds some documentation, orders the functions into a (hopefully more useful) library category, and adds some manuals for the main features with usage examples. - [x] Once the QEDbase PR is merged, the @extref in particles.jl has to be enabled. The vectors manual is currently more of a place holder because I don't know enough about them to write a good manual. I would refer this task to @szabo137 or @steindev . The phase space definition manual is also a placeholder, because it will be reworked soon anyway (see #50).
QEDjl-project · Oct 22, 2024 · fc1483b · fc1483b
2 parents 56610d7 + cf5f65d
commit fc1483b
Show file tree

Hide file tree

Showing 15 changed files with 525 additions and 30 deletions.
diff --git a/.gitignore b/.gitignore
@@ -1,2 +1,5 @@
 *Manifest.toml
 docs/build/
+
+docs/src/particles_manual.ipynb
+docs/src/particles_manual.md
diff --git a/README.md b/README.md
@@ -1,8 +1,41 @@
-# QEDcore
+# QEDcore.jl
 
 [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/stable/)
 [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://QEDjl-project.github.io/QEDcore.jl/dev/)
-[![Build Status](https://github.com/QEDjl-project/QEDcore.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/QEDjl-project/QEDcore.jl/actions/workflows/CI.yml?query=branch%3Amain)
 [![Code Style: Blue](https://img.shields.io/badge/code%20style-blue-4495d1.svg)](https://github.com/invenia/BlueStyle)
 
 This package is part of the `QuantumElectrodynamics.jl` library. For the description of the interoperability with other packages of `QuantumElectrodynamics.jl` see [docs](https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/).
+
+This package's main purpose is to provide implementations of the basic interfaces defined in [`QEDbase.jl`](https://github.com/QEDjl-project/QEDbase.jl), such as various particle types, `PhasespaceDefinition`, `PhaseSpacePoint`, and various vector and matrix types. These types are used across most of the QEDjl-project repositories. For detailed information on these types, please refer to the respective pages in the [docs](https://qedjl-project.github.io/QEDcore.jl/dev/).
+
+## Contributing
+
+Contributions are welcome! If you'd like to report a bug, suggest an enhancement, or contribute
+code, please feel free to open an issue or submit a pull request.
+
+To ensure consistency across the `QuantumElectrodynamics.jl` ecosystem, we encourage all contributors
+to review the [QuantumElectrodynamics.jl contribution guide](https://qedjl-project.github.io/QuantumElectrodynamics.jl/stable/dev_guide/#Development-Guide).
+
+## Credits and contributors
+
+This work was partly funded by the Center for Advanced Systems Understanding (CASUS) that
+is financed by Germany’s Federal Ministry of Education and Research (BMBF) and by the Saxon
+Ministry for Science, Culture and Tourism (SMWK) with tax funds on the basis of the budget
+approved by the Saxon State Parliament.
+
+The core code of the package `QEDcore.jl` is developed by a small team at the Center for
+Advanced Systems Understanding ([CASUS](https://www.casus.science)), namely
+
+### Core Contributors
+
+- **Uwe Hernandez Acosta** (CASUS/HZDR, [u.hernandez@hzdr.de](mailto:u.hernandez@hzdr.de))
+- **Anton Reinhard** (CASUS/HZDR)
+- **Simeon Ehrig** (CASUS/HZDR)
+
+### Former Contributors
+
+We extend our sincere thanks to all contributors who have supported this project.
+
+## License
+
+[MIT](LICENSE) © Uwe Hernandez Acosta
diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,5 +1,8 @@
 [deps]
+BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterInterLinks = "d12716ef-a0f6-4df4-a9f1-a5a34e75c656"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 QEDbase = "10e22c08-3ccb-4172-bfcf-7d7aa3d04d93"
 QEDcore = "35dc0263-cb5f-4c33-a114-1d7f54ab753e"
 QEDprocesses = "46de9c38-1bb3-4547-a1ec-da24d767fdad"
diff --git a/docs/make.jl b/docs/make.jl
@@ -5,23 +5,98 @@ using Pkg
 project_path = Base.Filesystem.joinpath(Base.Filesystem.dirname(Base.source_path()), "..")
 Pkg.develop(; path=project_path)
 
-Pkg.add(; url="https://github.com/QEDjl-project/QEDbase.jl/", rev="dev")
-
+using QEDbase
 using QEDcore
+using QEDprocesses
+
 using Documenter
+using DocumenterInterLinks
+using Literate
 
-# DocMeta.setdocmeta!(QEDcore, :DocTestSetup, :(using QEDcore); recursive=true)
-
-makedocs(;
-    modules=[QEDcore],
-    authors="Uwe Hernandez Acosta <u.hernandez@hzdr.de>",
-    sitename="QEDcore.jl",
-    format=Documenter.HTML(;
-        canonical="https://QEDjl-project.github.io/QEDcore.jl",
-        edit_link="main",
-        assets=String[],
-    ),
-    pages=["Home" => "index.md"],
+# setup interlinks
+links = InterLinks(
+    "QuantumElectrodynamics" => "https://qedjl-project.github.io/QuantumElectrodynamics.jl/dev/",
+    "QEDbase" => "https://qedjl-project.github.io/QEDbase.jl/dev/",
+    "QEDcore" => "https://qedjl-project.github.io/QEDcore.jl/dev/",
+    "QEDprocesses" => "https://qedjl-project.github.io/QEDprocesses.jl/dev/",
 )
 
+# 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/ps_def.jl"),
+    Base.Filesystem.joinpath(project_path, "docs/src/tutorial/particles.jl"),
+    Base.Filesystem.joinpath(project_path, "docs/src/tutorial/vectors.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",
+    "Tutorials" => [
+        "Phase Space Definitions" => joinpath(tutorial_output_dir_name, "ps_def.md"),
+        "Particles and Phase Space Points" =>
+            joinpath(tutorial_output_dir_name, "particles.md"),
+        "Matrix and Vector Types" => joinpath(tutorial_output_dir_name, "vectors.md"),
+    ],
+    "API reference" => [
+        "Contents" => "library/outline.md",
+        "Particles" => "library/particles.md",
+        "Phase Space Definition" => "library/phasespacedef.md",
+        "Phase Space Points" => "library/phasespacepoint.md",
+        "Vector Types" => "library/vectors.md",
+        "Lorentz Boosts" => "library/lorentzboosts.md",
+        "Index" => "library/index.md",
+    ],
+]
+
+try
+    # generate markdown files with Literate.jl
+    for file in literate_paths
+        Literate.markdown(file, tutorial_output_dir; documenter=true)
+    end
+    # geneate docs with Documenter.jl
+
+    makedocs(;
+        modules=[QEDcore],
+        checkdocs=:exports,
+        authors="Uwe Hernandez Acosta",
+        repo=Documenter.Remotes.GitHub("QEDjl-project", "QEDcore.jl"),
+        sitename="QEDcore.jl",
+        format=Documenter.HTML(;
+            prettyurls=get(ENV, "CI", "false") == "true",
+            canonical="https://qedjl-project.gitlab.io/QEDcore.jl",
+            assets=String[],
+        ),
+        pages=pages,
+        plugins=[links],
+    )
+finally
+    # doing some garbage collection
+    @info "GarbageCollection: remove generated landing page"
+    rm(index_path)
+    @info "GarbageCollection: remove generated tutorial files"
+    rm(tutorial_output_dir; recursive=true)
+end
+
 deploydocs(; repo="github.com/QEDjl-project/QEDcore.jl", push_preview=false)
diff --git a/docs/src/index.md b/docs/src/index.md
diff --git a/docs/src/library/index.md b/docs/src/library/index.md
@@ -0,0 +1,10 @@
+```@meta
+CurrentModule = QEDcore
+```
+
+# QEDcore
+
+API index for [QEDcore](https://github.com/QEDjl-project/QEDcore.jl).
+
+```@index
+```
diff --git a/docs/src/library/lorentzboosts.md b/docs/src/library/lorentzboosts.md
@@ -0,0 +1,16 @@
+# Lorentz Boosts
+
+The following is an implementation of the [Lorentz Boost Interface](@extref QEDbase Lorentz-Vector) of QEDbase.jl.
+
+```@meta
+CurrentModule = QEDcore
+```
+
+```@docs
+Boost
+BetaVector
+BetaX
+BetaY
+BetaZ
+AbstractCoordinateTransformation
+```
diff --git a/docs/src/library/outline.md b/docs/src/library/outline.md
@@ -0,0 +1,5 @@
+## API Outline
+
+```@contents
+Pages = ["particles.md", "phasespacedef.md", "phasespacepoint.md", "vectors.md"]
+```
diff --git a/docs/src/library/particles.md b/docs/src/library/particles.md
@@ -0,0 +1,25 @@
+# Particles
+
+## Particle Types
+
+The following are subtypes of `QEDbase.AbstractParticleType`(@extref).
+
+For all these types the corresponding interface is implemented, including `QEDbase.base_state`(@extref) and `QEDbase.propagator`(@extref).
+
+```@meta
+CurrentModule = QEDcore
+```
+
+```@docs
+FermionLike
+BosonLike
+MajoranaFermion
+MajoranaBoson
+Fermion
+Boson
+AntiFermion
+AntiBoson
+Electron
+Positron
+Photon
+```
diff --git a/docs/src/library/phasespacedef.md b/docs/src/library/phasespacedef.md
@@ -0,0 +1,22 @@
+# Phase Space Definitions
+
+```@meta
+CurrentModule = QEDcore
+```
+
+## Phase Space Definition Type
+```@docs
+PhasespaceDefinition
+```
+
+## Frames of Reference
+```@docs
+CenterOfMomentumFrame
+ElectronRestFrame
+```
+
+## Coordinate Systems
+
+```@docs
+SphericalCoordinateSystem
+```
diff --git a/docs/src/library/phasespacepoint.md b/docs/src/library/phasespacepoint.md
@@ -0,0 +1,19 @@
+# Phase Space Points
+
+```@meta
+CurrentModule = QEDcore
+```
+
+## Types and Aliases
+```@docs
+ParticleStateful
+PhaseSpacePoint
+InPhaseSpacePoint
+OutPhaseSpacePoint
+```
+
+## Accessors
+```@docs
+getindex
+_momentum_type
+```
diff --git a/docs/src/library/vectors.md b/docs/src/library/vectors.md
@@ -0,0 +1,33 @@
+# Vector and Matrix Types
+
+```@meta
+CurrentModule = QEDcore
+```
+
+## 4-Momenta
+```@docs
+SFourMomentum
+MFourMomentum
+```
+
+## Spinors
+```@docs
+BiSpinor
+AdjointBiSpinor
+```
+
+## Lorentz Vectors
+```@docs
+SLorentzVector
+MLorentzVector
+```
+
+## Dirac Matrix
+```@docs
+DiracMatrix
+```
+
+## Multiplications
+```@docs
+_mul
+```