Merge pull request #22 from campa-consortium/dcs16/01

Doc reorg.
campa-consortium · Dec 18, 2024 · 995b164 · 995b164
2 parents 75fc716 + d0cb56c
commit 995b164
Show file tree

Hide file tree

Showing 10 changed files with 62 additions and 21 deletions.
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,2 @@
+# MyST build outputs
+_build
diff --git a/README.md b/README.md
@@ -7,6 +7,11 @@ An effort to create a standard to promote lattice information exchange for parti
 As part of this effort, we focus on the physical layout and properties of a machine.
 This excludes description of tracking of particles including collective effects.
 
+## Participation
+
+There are weekly (more or less) meetings to discuss development of the lattice standard.
+To participate in the creation of the lattice standard, please contact [Jean-Luc Vay](https://https://github.com/jlvay) to be put on the mailing list.
+
 ## Roadmap
 
 1. **Reach out to the community (continuous)**

diff --git a/CONTRIBUTING.md → front_matter/contributing.md b/CONTRIBUTING.md → front_matter/contributing.md
@@ -1,4 +1,4 @@
-# Contributing
+# How to Contribute
 
 Follow these steps **only once**:
 1. Go to https://github.com/campa-consortium/lattice-standard.

diff --git a/section_documentation.md → front_matter/doc_editing_setup.md b/section_documentation.md → front_matter/doc_editing_setup.md
@@ -1,4 +1,6 @@
-# Documentation
+# Documentation Editing Setup
+
+The documentation uses the [MyST](https://mystmd.org/) markup language. 
 
 Install the following packages within an existing conda environment:
 ```{code} bash

diff --git a/GOVERNANCE.md → front_matter/governance.md b/GOVERNANCE.md → front_matter/governance.md
diff --git a/front_matter/introduction.md b/front_matter/introduction.md
@@ -0,0 +1,38 @@
+# Accelerator Lattice Standard
+
+This standard is an effort to create a standard to promote lattice information exchange for particle accelerators.
+
+## Scope
+
+The standard focuses on the physical layout and properties of a machine.
+This excludes description of tracking of particles including collective effects.
+
+## Participation
+
+There are weekly (more or less) meetings to discuss development of the lattice standard.
+To participate in the creation of the lattice standard, please contact [Jean-Luc Vay](https://https://github.com/jlvay) to be put on the mailing list.
+
+## Roadmap
+
+1. **Reach out to the community (continuous)**
+
+2. **Request for documentation:** 
+   * Goal: document how various accelerator modeling codes already do for their lattices.
+   * Organizers: Create a template.
+     * element parameters
+     * lines/beamlines: how are elements distributed
+     * example of a facility/lattice
+   * Community: to fill out a template per existing code.
+
+3. **Request for proposals:** how would we like to describe lattices and individual elements in terms of physical line & element properties?
+   * Goal: write down as text document (standard)
+     * use a simple bullet point document, e.g., with name of element, purpose, properties and alternates
+   * Form community consensus on:
+     * elements: which properties to put in the standard we are developing; which alternate descriptions do we need for the same element?
+     * lines/beamlines: which descriptions (e.g., sub-lines, channels/repetitions, line order inversion, physical line inversion, constants/variables to scale lines, etc.) do we need in the standard we are developing or which ones belong in implementations
+
+4. **Request for proposals:** how would we like to store & exchange lattices in the 21st century?
+   * Goal: document advise to implementers.
+   * How can we programming language agnostic store and exchange lattices?
+     * examples for storage formats: TOML, YAML, JSON, XML, ... (with the right framework, one can support them all)
+     * examples for frameworks (import/export/validation): [pydantic](https://docs.pydantic.dev) (Python), [StructTypes.jl](https://github.com/JuliaData/StructTypes.jl)/[Parameters.jl](https://github.com/mauro3/Parameters.jl) in Julia, etc.
diff --git a/pull_request_template.md → front_matter/pull_request_template.md b/pull_request_template.md → front_matter/pull_request_template.md
diff --git a/myst.yml b/myst.yml
@@ -2,17 +2,23 @@
 version: 1
 project:
   id: 04669581-a5a2-47e4-8d37-bf222bc14229
-  title: Accelerator Lattice Standard
+  title: 'Particle Accelerator Description Standard'
   # description:
   # keywords: []
   # authors: []
   github: https://github.com/campa-consortium/lattice-standard
   toc:
-    - file: 'README.md'
-    - file: 'GOVERNANCE.md'
-    - file: 'CONTRIBUTING.md'
-    - file: 'section_documentation.md'
-    - file: 'section_example.md'
+    - file: 'front_matter/introduction.md'
+    - title: 'Front Matter'
+      children:
+        - file: 'front_matter/organization.md'
+        - file: 'front_matter/governance.md'
+        - file: 'front_matter/contributing.md'
+        - file: 'front_matter/doc_editing_setup.md'
+    - title: 'Lattice Standard'
+      children:
+        - file: 'standard/introduction.md'
+        - file: 'standard/element_parameter.md'
 site:
   template: book-theme
   #domains:

diff --git a/section_example.md b/section_example.md
diff --git a/standard/standard.md → standard/introduction.md b/standard/standard.md → standard/introduction.md
@@ -1,4 +1,4 @@
-# Accelerator Lattace Standard
+# Introduction
 
 ## Overview