docs: obsidian compatible (#41)

* docs: obsidian compatible

* docs: separate publish vs dev

* docs: workflow

* docs: bugfix

* docs: bugfix

.github/workflows/doc.yaml

@@ -7,7 +7,7 @@ on:
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: false
+  cancel-in-progress: true
 
 permissions:
   contents: write  # To push a branch
@@ -34,15 +34,13 @@ jobs:
           cargo install mdbook-admonish --force
           cargo install mdbook-katex --force
           cargo install mdbook-mermaid --force
+          cargo install mdbook-yml-header --force
 
       - name: Setup Pages
         uses: actions/configure-pages@v5
 
       - name: Build Book
-        run: |
-          mdbook-admonish install .
-          mdbook-mermaid install .
-          mdbook build
+        run: mdbook build docs
 
       - name: Make target directory so build doesn't crash
         run: mkdir -p target

.gitignore

@@ -22,3 +22,7 @@ Cargo.lock
 
 # This file contains environment-specific configuration like linker settings
 .cargo/config.toml
+
+# Docs exclude
+.obsidian/
+docs/book/

book.toml → docs/book.toml

@@ -3,10 +3,9 @@ authors = ["Philip Linden"]
 language = "en"
 multilingual = false
 title = "spacetime documentation"
-src = "docs"
 
 [build]
-build-dir = "docs/book"
+build-dir = "book"
 create-missing = false
 
 [output.html]
@@ -16,8 +15,8 @@ smart-punctuation = true
 git-repository-url = "https://github.com/philiplinden/spacetime"
 git-repository-icon = "fa-github"
 edit-url-template = "https://github.com/philiplinden/spacetime/edit/main/docs/{path}"
-additional-css = ["./docs/plugins/mdbook-admonish.css"]
-additional-js = ["./docs/plugins/mermaid.min.js", "./docs/plugins/mermaid-init.js"]
+additional-css = ["./plugins/mdbook-admonish.css"]
+additional-js = ["./plugins/mermaid.min.js", "./plugins/mermaid-init.js"]
 
 [output.html.print]
 enable = true    # include support for printable output
@@ -38,3 +37,5 @@ command = "mdbook-mermaid"
 
 [preprocessor.katex]
 after = ["links"]
+
+[preprocessor.yml-header]

docs/dev/log/2024-12-08.md

@@ -0,0 +1,15 @@
+## 2024-12-08
+
+I switched the docs to use mdbook today and I'm feeling good about diving back
+in to this project. Previous devlogs are available on the repository's
+[archive](https://github.com/philiplinden/spacetime/tree/main/archive/devlog).
+
+Since the last devlog I've gotten a lot more experience with Rust and Bevy. I
+have a strong sense of how to structure a Bevy project and I'm comfortable with
+its features now, so I'm ready to drop krabmaga and start building the project
+from scratch.
+
+To start, I'm going to build the simulation without any rendering or graphics.
+Just enough to see what's happening through logs or maybe egui. Unlike previous
+attempts, I'm going to focus on implementing the math from the research papers I
+found, rather than trying to jump straight to the end goal.

docs/dev/log/2024-12-15.md

@@ -0,0 +1,20 @@
+## 2024-12-15
+
+Here are two videos that really helped me find intuitions for the math of
+general relativity:
+
+- https://youtu.be/OpOER8Eec2A?si=22VBvAKu8VV6ye5E
+- https://youtu.be/S78h8zQwQe0?si=1ptIvQqqiFlSOqdG
+
+I think it would be helpful to make this app demonstrate these intuitions. Let's
+follow the videos' trains of thought and see if we can implement them along the
+way. One thing these videos do very well is to build up ideas bit by bit.
+Similarly, I think we can build up the app's features bit by bit.
+
+While the math _could_ be implemented with real physical constants, it would be
+much easier to see what's happening if we use simple scale factors, especially
+if we can change them on the fly.
+
+I've said this before and I'll say it again: I am a huge fan of the "retro
+radar" aesthetic. It would be fun to lean into that. Here is a Pinterest board
+for inspiration: https://pin.it/CgMRWzHFl

docs/dev/log/2024-12-22.md

@@ -0,0 +1,13 @@
+## 2024-12-22
+
+I watched a very insightful video series that explains special relativity in a
+way that I think is very intuitive. I think it would be helpful to implement
+these intuitions here.
+
+- [Special Relativity Intuitions](https://www.youtube.com/playlist?list=PLawLaqps30oBmdbw_D-AI1RQUoCO7Wr1K)
+  - [Speed of light is constant in all reference frames](https://youtu.be/hi57CA3GZy4?si=MbhF4UMP-ILTdM9f)
+  - [Everything moves at the speed of light](https://youtu.be/TJmgKdc7H34?si=CBHYgsgn1oh3ilZj)
+- [General Relativity Intuitions](https://www.youtube.com/playlist?list=PLawLaqps30oAcpVd4r-wj8hGodzpPRYTT)
+  - [How gravity bends light even though it has no mass](https://youtu.be/05jFhuRs-w0)
+  - [Gravity comes from time curving space](https://youtu.be/OpOER8Eec2A)
+  - [Curved spacetime changes trajectories of light and matter](https://www.youtube.com/watch?v=S78h8zQwQe0)

docs/dev/log/2024-12-23.md

@@ -0,0 +1,11 @@
+## 2024-12-23
+
+I reworked the docs on relativity, more to come.
+
+I started a new repo to use for manim figures:
+[philiplinden/manim-sandbox](https://github.com/philiplinden/manim-sandbox)
+
+I think this repo should basically be an interactive implementation of the
+visualizations described
+[here](https://youtu.be/wrwgIjBUYVc?si=aY4raU4TI56Kl7XV) and
+[here](https://youtu.be/YNqTamaKMC8?si=jMuLrQSQaqbRfsB8)

docs/dev/log/2024-12-30.md

@@ -0,0 +1,3 @@
+## 2024-12-30
+
+More relativity docs.

docs/dev/log/2025-01-01.md

@@ -0,0 +1,2 @@
+More time making an animation to show time dilation with the light clock
+example.

docs/dev/log/2025-01-04.md

@@ -0,0 +1,21 @@
+I've been working on the [fundamentals of relativity](/relativity/00-index.md)
+for a while and I'm finally starting to dig in to the applications. I need to
+have a firm understanding of [](/relativity/vectors/00-index.md) so I can implement it in the app.
+
+I've split the docs into two sections: _Intuition_ and _Application_. The
+_Intuition_ section is for the fundamental concepts of relativity. The
+_Application_ section is for the hard math and implementation details.
+
+I have a pretty good idea of what I want the app to look like. Short version is
+- I want to be able to select a reference frame and inspect the observed time of
+other objects. 
+- I also want to visualize gravity and the curvature of spacetime like the
+  visualizations here: https://youtu.be/wrwgIjBUYVc?si=b-SFIhcVsm5MMwco
+- A more advanced version would be to ray-trace signal paths through spacetime and
+  perhaps show length contraction.
+- I want to use exaggerated scale factors to demonstrate the effects and make
+  the math simpler. Things like the speed of light, gravitational constant,
+  etc.
+
+I think the visualizations will probably use a shader. I found a good resource
+for learning shaders here: https://thebookofshaders.com/

docs/dev/log/2025-01-05.md

@@ -0,0 +1,8 @@
+I am going to try using Obsidian to manage the docs. Since I prefer Obsidian's
+title-is-the-filename convention, I added a new preprocessor to automatically
+generate a SUMMARY.md file every build and there will be a huge diff.
+
+The conventions I'm using for file names are listed in the readme for the
+preprocessor: https://github.com/elmdash/mdbook-fs-summary/blob/main/README.md -- Actually this preprocessor didn't work so well. Last update was years ago too. I think I'll drop the idea of auto-generated summary files for now.
+
+This plugin does look useful for making the docs compatible/friendly with obsidian: https://github.com/dvogt23/mdbook-yml-header By using this plugin I can shamelessly add obsidian front matter.

docs/research-papers/index.md

@@ -1,9 +1,9 @@
 # Research Papers
 
-- [Relativity](relativity/00-index.md)
-  - [**A Relativistic Framework for Coordinated Lunar Time**](A%20relativistic%20framework%20for%20coordinated%20lunar%20time.pdf)
+- [Relativity](/relativity/00-index.md)
+  - [**A Relativistic Framework for Coordinated Lunar Time**](/research-papers/A%20relativistic%20framework%20for%20coordinated%20lunar%20time.pdf)
     (_Neil Ashbya & Bijunath R. Patlab, 2024_)
-  - [**Looking for a Lunar Reference Timescale**](Looking%20for%20a%20Lunar%20Reference%20Timescale.pdf)
+  - [**Looking for a Lunar Reference Timescale**](/research-papers/Looking%20for%20a%20Lunar%20Reference%20Timescale.pdf)
     (_Frédéric Meynadier, Pascale Defraigne, 2024_)
 - [Timekeeping](timekeeping/00-index.md)
   - [**The Clock Model and Its Relationship with the Allan and Related Variances**](The%20Clock%20Model%20and%20Its%20Relationship%20with%20the%20Allan%20and%20Related%20Variances.pdf)
@@ -13,5 +13,5 @@
 - [Positioning, Navigation, and Timing Networks](pnt-networks/index.md)
   - [**Time-transfer and clock-synchronization technique for microsatellites in the lunar region**](Time-transfer%20and%20clock-synchronization%20technique%20for%20microsatellites%20in%20the%20lunar%20region.pdf)
     (_Immacolata Fazzoletto, et al., 2023_)
-  - [**Design of a high-stability heterogeneous clock system for small satellites in LEO**](Design%20of%20a%20high-stability%20heterogeneous%20clock%20system%20for%20small%20satellites%20in%20LEO.pdf)
+  - [**Design of a high-stability heterogeneous clock system for small satellites in LEO**](/research-papers/Design%20of%20a%20high-stability%20heterogeneous%20clock%20system%20for%20small%20satellites%20in%20LEO.pdf)
     (_Damon Van Buren, Penina Axelrad, Scott Palo, 2021_)

docs/SUMMARY.md → docs/src/SUMMARY.md

@@ -20,7 +20,3 @@
 
 - [Relativistic Vector Math](relativity/vectors/00-index.md)
   - [Lorentz Boosts](relativity/vectors/01-lorentz-boost-intro.md)
-
----
-
-- [Devlog](devlog.md)

docs/index.md → docs/src/index.md

@@ -10,12 +10,9 @@ Positioning, Navigation, and Timing (PNT) service network configurations.
 This book serves as documentation for the `spacetime` project and a guide to the
 fundamental concepts that it seeks to model.
 
-- [Relativity](relativity/00-index.md)
-- [Timekeeping](timekeeping/00-index.md)
-- [Network Topology](network-topology/00-index.md)
-- [Lunar PNT](lunar-pnt/00-index.md)
-
-Research papers are available in the [research-papers](research-papers/index.md)
+Research papers are available in the [research-papers](../research-papers/index.md)
 section.
 
-And development notes are available in the [devlog](devlog.md).
+If you find a mistake or have a suggestion, please
+[open an issue](https://github.com/philiplinden/spacetime/issues/new) and let me
+know about it!

docs/relativity/general/00-index.md → docs/src/relativity/general/00-index.md

@@ -17,7 +17,7 @@ continuous _spacetime_.
 In Newtonian physics, gravity is a force that pulls objects together. On Earth,
 this would look like a uniform force acting on all objects pulling them towards
 the ground. But our exploration of Einstein's postulate on
-[inertial reference frames](relativity/00-index.md#inertial-reference-frames)
+[inertial reference frames](/relativity/00-index.md#inertial-reference-frames)
 showed us that we can "flip" our reference frame and the physics are the same
 By this definition it is impossible to tell if you are at rest or in motion. So
 taking that to the extreme, maybe you are at rest and the Earth is accelerating
@@ -52,11 +52,11 @@ following video does an excellent job of explaining it:
 
 Video: [Gravity comes from time curving space](https://youtu.be/OpOER8Eec2A)
 
-![alt text](./assets/image.png)
+![alt text](/relativity/general/assets/image.png)
 
-![alt text](./assets/image2.png)
+![alt text](/relativity/general/assets/image2.png)
 
-![alt text](./assets/image3.png)
+![alt text](/relativity/general/assets/image3.png)
 
 ## Curved spacetime
 

docs/relativity/special/02-time-dilation.md → docs/src/relativity/special/02-time-dilation.md

@@ -89,7 +89,7 @@ one reference frame than in another is if the elapsed time experienced by a
 moving object, $\Delta \tau$, "dilates" compared to the elapsed time
 experienced by an observer at rest in the reference frame, $\Delta t$.
 
-![time dilation](./assets/TimeDilationDemo.gif)
+![time dilation](/relativity/special/assets/TimeDilationDemo.gif)
 
 Therefore, the time dilation equation is:
 

docs/relativity/special/03-length-contraction.md → docs/src/relativity/special/03-length-contraction.md

@@ -4,7 +4,7 @@
 
 The relative speed between two inertial reference frames, $v$, is the same in
 both frames. Think about the astronaut and astronomer in the light clock example
-from [the previous chapter](./02-time-dilation.md).
+from [the previous chapter](02-time-dilation.md).
 
 - The astronaut observes the astronomer moving at a constant speed, $v$.
 - The astronomer observes the astronaut moving at a constant speed, $v$.

docs/relativity/vectors/01-lorentz-boost-intro.md → docs/src/relativity/vectors/01-lorentz-boost-intro.md

@@ -9,10 +9,10 @@ $y$, and $z$ spatial components to remind us that these are vectors in 3D space.
 
 $$
 \begin{align*}
-\text{position\quad}& s = \begin{bmatrix} x \\ y \\ z \end{bmatrix}\\
-\text{velocity\quad}& \dot{s} = \begin{bmatrix} \dot{x} \\ \dot{y} \\
+\text{position}& \quad s = \begin{bmatrix} x \\ y \\ z \end{bmatrix}\\
+\text{velocity}& \quad \dot{s} = \begin{bmatrix} \dot{x} \\ \dot{y} \\
 \dot{z} \end{bmatrix} = \frac{d\vec{s}}{dt}(t)\\
-\text{acceleration\quad}& \ddot{s} = \begin{bmatrix} \ddot{x} \\ \ddot{y} \\
+\text{acceleration}& \quad \ddot{s} = \begin{bmatrix} \ddot{x} \\ \ddot{y} \\
 \ddot{z} \end{bmatrix} = \frac{d^2\vec{s}}{dt^2}(t)
 \end{align*}
 $$