Skip to content

Conversation

@ethanjli
Copy link
Member

This PR attempts to fix a DX complexity problem with editing the docs (as reported to me by @tcebron in a Slack DM conversation), in which Python is required for previewing docs in the editor due to the need for Python to copy in the software changelog (from /software/CHANGELOG.md) and hardware assets (from /hardware) into the MkDocs documentation directory tree. This PR attempts to simplify things by instead symlinking to those external assets from within the MkDocs directory tree.

@ethanjli
Copy link
Member Author

ethanjli commented Feb 11, 2025

It looks like GitHub doesn't follow symlinks, so in GitHub's preview does not correctly follow any links to files in the symlinked directory documentation/docs/assets/hardware. I will wait to see whether Zettlr (which is used by @tcebron) correctly follows symlinks; if not (or if we decide that broken hardware asset links in the GitHub preview are intolerable), we might have to move all hardware design files from hardware into documentation/docs/assets/hardware and change hardware to be a symlink to documentation/docs/assets/hardware.

@ethanjli ethanjli marked this pull request as ready for review February 20, 2025 05:06
@ethanjli
Copy link
Member Author

I think this is an improvement over the current DX, and I don't think there are any regressions with it, so I'm going to merge this PR now even though @tcebron hasn't tested how well it works with Zettlr yet. If we later decide we want to move everything in /hardware into /documentation/docs/assets/hardware and replace the former with a symlink to the latter (i.e. reversing the current symlink directionality), we can do that in a future PR.

@ethanjli ethanjli added this pull request to the merge queue Feb 20, 2025
Merged via the queue into master with commit 5a5f375 Feb 20, 2025
3 checks passed
@ethanjli ethanjli deleted the fix/mkdocs-simpler-repo-assets branch February 20, 2025 05:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

Status: ✅ Done

Development

Successfully merging this pull request may close these issues.

2 participants