From 4bae9ee8ceb350ec468d4fa1a016cda4ee1dee4b Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 09:15:39 -0600 Subject: [PATCH 1/8] install mkdocs-exclude --- .github/workflows/sync-wiki3.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/sync-wiki3.yaml b/.github/workflows/sync-wiki3.yaml index a7e037ec..9d00b44c 100644 --- a/.github/workflows/sync-wiki3.yaml +++ b/.github/workflows/sync-wiki3.yaml @@ -25,7 +25,7 @@ jobs: run: | sudo apt update sudo apt install sshpass - pip install mkdocs mkdocs-ezlinks-plugin + pip install mkdocs mkdocs-ezlinks-plugin mkdocs-exclude - name: Generate static pages using mkdocs run: | From 90c3635ceee30cf1e6a4876ffaeb4297f1856d36 Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 09:19:53 -0600 Subject: [PATCH 2/8] add to config --- mkdocs/mkdocs.yaml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/mkdocs/mkdocs.yaml b/mkdocs/mkdocs.yaml index ee02a851..0d1f780a 100644 --- a/mkdocs/mkdocs.yaml +++ b/mkdocs/mkdocs.yaml @@ -9,6 +9,10 @@ plugins: - search - ezlinks: wikilinks: true + - exclude: + glob: + - mkdocs/* + markdown_extensions: - sane_lists - md_in_html From d5212004509d160b90c458d2fe313b4a9d3afc94 Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 09:27:41 -0600 Subject: [PATCH 3/8] change doc --- HOWTO-Test-Doc-Changes.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/HOWTO-Test-Doc-Changes.md b/HOWTO-Test-Doc-Changes.md index 3cdd249d..b878293d 100644 --- a/HOWTO-Test-Doc-Changes.md +++ b/HOWTO-Test-Doc-Changes.md @@ -33,9 +33,9 @@ You need to set up an access token in your repository secrets for Actions. The easiest way to test Wiki3 is locally. You could also set up a webserver and your repository secrets to let the workflow upload it for you, but here I'll just explain how to test locally. The full instructions for installing MkDocs can be found [here](https://www.mkdocs.org/user-guide/installation/), but the short version is to run `pip install mkdocs`. -You will also need the EzLinks plugin, which you can install with `pip install mkdocs-ezlinks-plugin`. +You will also need some plugin, which you can install with `pip install mkdocs-ezlinks-plugin mkdocs-exclude`. Once MkDocs is installed, you can now generate the site. I do this with a one-liner, run from the root directory of the repo: -`cd mkdocs; rm -r docs site; mkdir docs; cp -r ../!(mkdocs) docs; cp style.css docs; mkdocs build; cd ..` +`cd mkdocs; ln -s .. docs; cp style.css ..; mkdocs build; cd ..; rm style.css` MkDocs expects the Markdown documentation files to be in a "docs" subdirectory, so we create it and move everything to it, and then we can go ahead and build the site. From 749a4eafaad2cfdb443a1080fc300d04d0afbf7e Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 09:36:21 -0600 Subject: [PATCH 4/8] update scripts --- bin/mkdocs-install.sh | 3 +-- bin/mkdocs-run.sh | 9 +++++---- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/bin/mkdocs-install.sh b/bin/mkdocs-install.sh index 6242f94f..3aba954c 100755 --- a/bin/mkdocs-install.sh +++ b/bin/mkdocs-install.sh @@ -1,10 +1,9 @@ #!/bin/bash sudo apt update -sudo apt install ncftp # sudo apt install python-pip for 'pip' sudo apt install python3-pip # pip did not work for in my case? -pip install mkdocs mkdocs-ezlinks-plugin \ No newline at end of file +pip install mkdocs mkdocs-ezlinks-plugin mkdocs-exclude diff --git a/bin/mkdocs-run.sh b/bin/mkdocs-run.sh index a0618946..fc804c5d 100755 --- a/bin/mkdocs-run.sh +++ b/bin/mkdocs-run.sh @@ -1,7 +1,8 @@ #!/bin/bash -shopt -s extglob cd mkdocs -mkdir docs -cp -r ../!(mkdocs) docs -mkdocs build \ No newline at end of file +ln -s .. docs +cp style.css .. +mkdocs build --strict +cd .. +rm style.css From 52c00dd005f4a07d7ed6d93c2c48c44cc3672560 Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 09:40:26 -0600 Subject: [PATCH 5/8] update docs to use scripts --- HOWTO-Test-Doc-Changes.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/HOWTO-Test-Doc-Changes.md b/HOWTO-Test-Doc-Changes.md index b878293d..22360edc 100644 --- a/HOWTO-Test-Doc-Changes.md +++ b/HOWTO-Test-Doc-Changes.md @@ -32,10 +32,9 @@ You need to set up an access token in your repository secrets for Actions. The easiest way to test Wiki3 is locally. You could also set up a webserver and your repository secrets to let the workflow upload it for you, but here I'll just explain how to test locally. -The full instructions for installing MkDocs can be found [here](https://www.mkdocs.org/user-guide/installation/), but the short version is to run `pip install mkdocs`. -You will also need some plugin, which you can install with `pip install mkdocs-ezlinks-plugin mkdocs-exclude`. +The full instructions for installing MkDocs can be found [here](https://www.mkdocs.org/user-guide/installation/), but there is also a script included in the repo that will install it for you. +Run `bash ./bin/mkdocs-install.sh` if you have a Debian/apt-based system. If not, read the script to find which python packages you need to install. Once MkDocs is installed, you can now generate the site. -I do this with a one-liner, run from the root directory of the repo: -`cd mkdocs; ln -s .. docs; cp style.css ..; mkdocs build; cd ..; rm style.css` -MkDocs expects the Markdown documentation files to be in a "docs" subdirectory, so we create it and move everything to it, and then we can go ahead and build the site. +There is a script included to do this as well. +Run `bash ./bin/mkdocs-run.sh`, and the site files will then be found at ./mkdocs/site From 794ce784e498f5b12867706817d506db71c4f31c Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 12:29:15 -0600 Subject: [PATCH 6/8] move sitemap link --- Home.md | 4 +++- mkdocs/mkdocs.yaml | 1 - 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/Home.md b/Home.md index 7cc75776..e0f6100c 100644 --- a/Home.md +++ b/Home.md @@ -69,4 +69,6 @@ So you are thinking of doing an engine control project. You have stopped by the ### [![Miata rusEFI Racecar!](https://user-images.githubusercontent.com/5051341/80621997-bf7bf000-8a0d-11ea-998e-48fc3accba59.png)](https://www.youtube.com/embed/3xz66oR95F8?start=8 "Miata rusEFI Racecar!") -### [![BMW V12 with dual ETB!](https://user-images.githubusercontent.com/5051341/80622501-809a6a00-8a0e-11ea-8efc-b575def1d132.png)](https://www.youtube.com/embed/TGf8IMwRuIY "BMW V12 with dual ETB!") +### [![BMW V12 with dual ETB!](https://user-images.githubusercontent.com/5051341/80622501-809a6a00-8a0e-11ea-8efc-b575def1d132.png)](https://www.youtube.com/embed/TGf8IMwRuIY "BMW V12 with dual ETB!") + +[Sitemap](sitemap.xml) diff --git a/mkdocs/mkdocs.yaml b/mkdocs/mkdocs.yaml index 0d1f780a..9dff20d9 100644 --- a/mkdocs/mkdocs.yaml +++ b/mkdocs/mkdocs.yaml @@ -87,4 +87,3 @@ nav: - 'Misc': - 'How to convert from carburetor to EFI': how-to-convert-from-carburetor-to-EFI.md - 'Do I need a wideband oxygen sensor?': do-i-need-wideband-oxygen-sensor.md - - 'Sitemap': sitemap.xml From c15166ddd35b6fe018ce47ae457a06d308b6e861 Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 12:52:22 -0600 Subject: [PATCH 7/8] use scripts --- .github/workflows/sync-wiki3.yaml | 9 ++------- 1 file changed, 2 insertions(+), 7 deletions(-) diff --git a/.github/workflows/sync-wiki3.yaml b/.github/workflows/sync-wiki3.yaml index 9d00b44c..55e409b7 100644 --- a/.github/workflows/sync-wiki3.yaml +++ b/.github/workflows/sync-wiki3.yaml @@ -25,16 +25,11 @@ jobs: run: | sudo apt update sudo apt install sshpass - pip install mkdocs mkdocs-ezlinks-plugin mkdocs-exclude + bash ./bin/mkdocs-install.sh - name: Generate static pages using mkdocs run: | - shopt -s extglob - cd mkdocs - mkdir docs - cp -r ../!(mkdocs) docs - cp style.css docs - mkdocs build + bash ./bin/mkdocs-run.sh - name: Set SSH variables env: From 558445557704f2bd4215f427b161a0a26aac4e3c Mon Sep 17 00:00:00 2001 From: David Holdeman Date: Sun, 1 Jan 2023 13:00:20 -0600 Subject: [PATCH 8/8] Use exclude plugin to allow symlinking instead of copying (#330) * install mkdocs-exclude * add to config * change doc * update scripts * update docs to use scripts * move sitemap link * use scripts --- .github/workflows/sync-wiki3.yaml | 9 ++------- HOWTO-Test-Doc-Changes.md | 9 ++++----- Home.md | 4 +++- bin/mkdocs-install.sh | 3 +-- bin/mkdocs-run.sh | 9 +++++---- mkdocs/mkdocs.yaml | 5 ++++- 6 files changed, 19 insertions(+), 20 deletions(-) diff --git a/.github/workflows/sync-wiki3.yaml b/.github/workflows/sync-wiki3.yaml index a7e037ec..55e409b7 100644 --- a/.github/workflows/sync-wiki3.yaml +++ b/.github/workflows/sync-wiki3.yaml @@ -25,16 +25,11 @@ jobs: run: | sudo apt update sudo apt install sshpass - pip install mkdocs mkdocs-ezlinks-plugin + bash ./bin/mkdocs-install.sh - name: Generate static pages using mkdocs run: | - shopt -s extglob - cd mkdocs - mkdir docs - cp -r ../!(mkdocs) docs - cp style.css docs - mkdocs build + bash ./bin/mkdocs-run.sh - name: Set SSH variables env: diff --git a/HOWTO-Test-Doc-Changes.md b/HOWTO-Test-Doc-Changes.md index 3cdd249d..22360edc 100644 --- a/HOWTO-Test-Doc-Changes.md +++ b/HOWTO-Test-Doc-Changes.md @@ -32,10 +32,9 @@ You need to set up an access token in your repository secrets for Actions. The easiest way to test Wiki3 is locally. You could also set up a webserver and your repository secrets to let the workflow upload it for you, but here I'll just explain how to test locally. -The full instructions for installing MkDocs can be found [here](https://www.mkdocs.org/user-guide/installation/), but the short version is to run `pip install mkdocs`. -You will also need the EzLinks plugin, which you can install with `pip install mkdocs-ezlinks-plugin`. +The full instructions for installing MkDocs can be found [here](https://www.mkdocs.org/user-guide/installation/), but there is also a script included in the repo that will install it for you. +Run `bash ./bin/mkdocs-install.sh` if you have a Debian/apt-based system. If not, read the script to find which python packages you need to install. Once MkDocs is installed, you can now generate the site. -I do this with a one-liner, run from the root directory of the repo: -`cd mkdocs; rm -r docs site; mkdir docs; cp -r ../!(mkdocs) docs; cp style.css docs; mkdocs build; cd ..` -MkDocs expects the Markdown documentation files to be in a "docs" subdirectory, so we create it and move everything to it, and then we can go ahead and build the site. +There is a script included to do this as well. +Run `bash ./bin/mkdocs-run.sh`, and the site files will then be found at ./mkdocs/site diff --git a/Home.md b/Home.md index 7cc75776..e0f6100c 100644 --- a/Home.md +++ b/Home.md @@ -69,4 +69,6 @@ So you are thinking of doing an engine control project. You have stopped by the ### [![Miata rusEFI Racecar!](https://user-images.githubusercontent.com/5051341/80621997-bf7bf000-8a0d-11ea-998e-48fc3accba59.png)](https://www.youtube.com/embed/3xz66oR95F8?start=8 "Miata rusEFI Racecar!") -### [![BMW V12 with dual ETB!](https://user-images.githubusercontent.com/5051341/80622501-809a6a00-8a0e-11ea-8efc-b575def1d132.png)](https://www.youtube.com/embed/TGf8IMwRuIY "BMW V12 with dual ETB!") +### [![BMW V12 with dual ETB!](https://user-images.githubusercontent.com/5051341/80622501-809a6a00-8a0e-11ea-8efc-b575def1d132.png)](https://www.youtube.com/embed/TGf8IMwRuIY "BMW V12 with dual ETB!") + +[Sitemap](sitemap.xml) diff --git a/bin/mkdocs-install.sh b/bin/mkdocs-install.sh index 6242f94f..3aba954c 100755 --- a/bin/mkdocs-install.sh +++ b/bin/mkdocs-install.sh @@ -1,10 +1,9 @@ #!/bin/bash sudo apt update -sudo apt install ncftp # sudo apt install python-pip for 'pip' sudo apt install python3-pip # pip did not work for in my case? -pip install mkdocs mkdocs-ezlinks-plugin \ No newline at end of file +pip install mkdocs mkdocs-ezlinks-plugin mkdocs-exclude diff --git a/bin/mkdocs-run.sh b/bin/mkdocs-run.sh index a0618946..fc804c5d 100755 --- a/bin/mkdocs-run.sh +++ b/bin/mkdocs-run.sh @@ -1,7 +1,8 @@ #!/bin/bash -shopt -s extglob cd mkdocs -mkdir docs -cp -r ../!(mkdocs) docs -mkdocs build \ No newline at end of file +ln -s .. docs +cp style.css .. +mkdocs build --strict +cd .. +rm style.css diff --git a/mkdocs/mkdocs.yaml b/mkdocs/mkdocs.yaml index ee02a851..9dff20d9 100644 --- a/mkdocs/mkdocs.yaml +++ b/mkdocs/mkdocs.yaml @@ -9,6 +9,10 @@ plugins: - search - ezlinks: wikilinks: true + - exclude: + glob: + - mkdocs/* + markdown_extensions: - sane_lists - md_in_html @@ -83,4 +87,3 @@ nav: - 'Misc': - 'How to convert from carburetor to EFI': how-to-convert-from-carburetor-to-EFI.md - 'Do I need a wideband oxygen sensor?': do-i-need-wideband-oxygen-sensor.md - - 'Sitemap': sitemap.xml