From 56e8ae60476ec995f08eb9d2a50454af2e4392c9 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Sun, 22 Mar 2026 19:57:40 +0100 Subject: [PATCH 1/8] update workflows --- .github/workflows/deploy.yml | 2 +- .github/workflows/spellcheck.yml | 2 +- requirements.txt | 2 +- run.sh | 4 ++-- 4 files changed, 5 insertions(+), 5 deletions(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index b982360..4a06f43 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -28,7 +28,7 @@ jobs: # Llista de tasques a executar - name: Install dependencies # Acció per instal·lar les dependències run: pip install -r requirements.txt - name: Build # Acció per compilar la documentació - run: mkdocs build --clean + run: properdocs build --clean - name: Upload static files as artifact # Acció per pujar els fitxers estàtics com a artefacte uses: actions/upload-pages-artifact@v3 with: diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index a1ed71f..89f7a41 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -57,7 +57,7 @@ jobs: # Llista de tasques a executar sudo apt update sudo apt install hunspell -y - name: Build documents # Acció per compilar la documentació - run: CI=false mkdocs build --clean + run: CI=false properdocs build --clean - name: Download dictionary # Acció per descarregar el diccionari que s'utilitzarà en el corrector ortogràfic run: | diff --git a/requirements.txt b/requirements.txt index d3410b1..fe38977 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -mkdocs-material-joapuiib~=3.0 +mkdocs-material-joapuiib~=4.0 mkdocs-materialx[imaging] mkdocs-git-committers-plugin-2~=2.5 diff --git a/run.sh b/run.sh index 0f9a114..8de4531 100755 --- a/run.sh +++ b/run.sh @@ -97,9 +97,9 @@ if [ $BUILD -eq 1 ]; then fi if [ $CI -eq 0 ]; then - mkdocs $COMMAND $ARGS + properdocs $COMMAND $ARGS else - CI=true mkdocs $COMMAND $ARGS + CI=true properdocs $COMMAND $ARGS fi if [ $? -ne 0 ]; then print "Error building site." From 22277df9aafd635cde45a7d1608e145bb1ad9f2c Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 25 Mar 2026 15:43:58 +0100 Subject: [PATCH 2/8] rename mkdocs.yml --- mkdocs.yml => properdocs.yml | 0 run.sh | 19 ++++++++++--------- 2 files changed, 10 insertions(+), 9 deletions(-) rename mkdocs.yml => properdocs.yml (100%) diff --git a/mkdocs.yml b/properdocs.yml similarity index 100% rename from mkdocs.yml rename to properdocs.yml diff --git a/run.sh b/run.sh index 8de4531..7598668 100755 --- a/run.sh +++ b/run.sh @@ -10,6 +10,8 @@ function print_error { RESET="\033[0m" echo -e "${RED}$1${RESET}" } +VENV_DIR=".venv" +GENERATOR="properdocs" BUILD=0 CI=0 @@ -72,24 +74,24 @@ if [ -n "$ACT" ]; then exit fi -if [ ! -d "venv" ]; then +if [ ! -d "$VENV_DIR" ]; then INSTALL_VENV=1 print "Virtual environment not found." fi if [ $INSTALL_VENV -eq 1 ]; then - if [ -d "venv" ]; then + if [ -d "$VENV_DIR" ]; then print "Removing existing virtual environment..." - rm -rf venv + rm -rf $VENV_DIR fi print "Installing virtual environment..." - python3 -m venv venv + python3 -m venv $VENV_DIR print "Installing dependencies" - ./venv/bin/pip install -r requirements.txt + $VENV_DIR/bin/pip install -r requirements.txt fi -source venv/bin/activate +source $VENV_DIR/bin/activate COMMAND="serve --livereload" if [ $BUILD -eq 1 ]; then @@ -97,9 +99,9 @@ if [ $BUILD -eq 1 ]; then fi if [ $CI -eq 0 ]; then - properdocs $COMMAND $ARGS + $GENERATOR $COMMAND $ARGS else - CI=true properdocs $COMMAND $ARGS + CI=true $GENERATOR $COMMAND $ARGS fi if [ $? -ne 0 ]; then print "Error building site." @@ -142,7 +144,6 @@ if [ $SPELL -eq 1 ]; then fi fi SPELL_SOURCES=$(echo "$SPELL_SOURCES" | grep 'docs/.*\.md$' | sed 's/\/index//' | sed 's/docs/site/' | sed 's/.md$/\/index.html/') - echo $SPELL_SOURCES for FILE in $SPELL_SOURCES; do if [ -f $FILE ]; then From 3c05495179792f2dd0db7e4f593f58558f9bcc20 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 25 Mar 2026 15:51:56 +0100 Subject: [PATCH 3/8] update informacio --- docs/informacio.md | 14 +++++++------- requirements.txt | 2 +- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/informacio.md b/docs/informacio.md index 75a2fb0..c6aaa6e 100644 --- a/docs/informacio.md +++ b/docs/informacio.md @@ -51,17 +51,17 @@ o [:octicons-comment-discussion-16: __Debat__][Discussions] abans per debatre el ## :fontawesome-solid-laptop-code: Desenvolupament Aquest lloc web està desenvolupat amb les següents eines i llibreries: -- __[MkDocs](https://www.mkdocs.org/){:target="_blank"}__: Generador de llocs web estàtics amb Markdown basat en Python. -- __[:simple-materialformkdocs: Material for MkDocs](https://squidfunk.github.io/mkdocs-material/){:target="_blank"}__: Tema per a MkDocs. -- __[Python Markdown](https://python-markdown.github.io/){:target="_blank"}__: Processador de Markdown per a Python. -- __[PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/){:target="_blank"}__: Extensions per a Python Markdown. -- __[Pygments](https://pygments.org/){:target="_blank"}__: Ressaltat de sintaxi del codi per a Python. +- __[:octicons-book-16: ProperDocs](https://www.properdocs.org/){:target="_blank"}__: Generador de llocs web estàtics amb Markdown basat en Python. +- __[:simple-materialformkdocs: MaterialX](https://jaywhj.github.io/mkdocs-materialx/){:target="_blank"}__: Tema per a ProperDocs. +- __[:material-language-markdown-outline: Python Markdown](https://python-markdown.github.io/){:target="_blank"}__: Processador de Markdown per a Python. +- __[:material-layers-plus: PyMdown Extensions](https://facelessuser.github.io/pymdown-extensions/){:target="_blank"}__: Extensions per a Python Markdown. +- __[:octicons-code-16: Pygments](https://pygments.org/){:target="_blank"}__: Ressaltat de sintaxi del codi per a Python. - __[:simple-git: Git](https://git-scm.com/){:target="_blank"}__: Sistema de control de versions. - __[:simple-github: GitHub](https://github.com/){:target="_blank"}__: Allotjament del codi font i la documentació. - __[:octicons-browser-24: GitHub Pages](https://pages.github.com/){:target="_blank"}__: Servei de pàgines web estàtiques de :simple-github: GitHub. - __[:octicons-play-24: GitHub Actions](https://github.com/features/actions){:target="_blank"}__: Automatització de tasques de :simple-github: GitHub. -- __[Diccionaris](https://github.com/Softcatala/catalan-dict-tools){:target="_blank"} de [:simple-softcatala: Softcatalà](https://www.softcatala.org/){:target="_blank"}__: +- __[:material-spellcheck: PySpelling](https://facelessuser.github.io/pyspelling/){:target="_blank"}__: Corrector ortogràfic. +- __[:material-book-check-outline: Diccionaris](https://github.com/Softcatala/catalan-dict-tools){:target="_blank"} de [:simple-softcatala: Softcatalà](https://www.softcatala.org/){:target="_blank"}__: Diccionaris utilitzats per a la correcció ortogràfica dels textos. -- __[PySpelling](https://facelessuser.github.io/pyspelling/){:target="_blank"}__: Corrector ortogràfic. - __[:simple-diagramsdotnet: draw.io](https://app.diagrams.net/){:target="_blank"}__: Web per a la creació de diagrames en línia. {.spell-ignore} diff --git a/requirements.txt b/requirements.txt index fe38977..d3410b1 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,3 +1,3 @@ -mkdocs-material-joapuiib~=4.0 +mkdocs-material-joapuiib~=3.0 mkdocs-materialx[imaging] mkdocs-git-committers-plugin-2~=2.5 From 02442b793bae3db92c39d27f69986b0d18eef681 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 25 Mar 2026 15:56:20 +0100 Subject: [PATCH 4/8] update pyspelling name --- .github/workflows/spellcheck.yml | 2 +- .pyspelling.yml | 2 +- run.sh | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index 89f7a41..808f9da 100644 --- a/.github/workflows/spellcheck.yml +++ b/.github/workflows/spellcheck.yml @@ -79,5 +79,5 @@ jobs: # Llista de tasques a executar echo "No files to check" exit 0 fi - SPELL_ARGS="$SPELL_ARGS --name mkdocs $SOURCES" + SPELL_ARGS="$SPELL_ARGS --name docs $SOURCES" pyspelling $SPELL_ARGS diff --git a/.pyspelling.yml b/.pyspelling.yml index faa4206..fad7c1b 100644 --- a/.pyspelling.yml +++ b/.pyspelling.yml @@ -2,7 +2,7 @@ spellchecker: hunspell jobs: 8 matrix: - - name: mkdocs + - name: docs pipeline: - pyspelling.filters.html: comments: false diff --git a/run.sh b/run.sh index 7598668..0a69d3e 100755 --- a/run.sh +++ b/run.sh @@ -150,7 +150,7 @@ if [ $SPELL -eq 1 ]; then SOURCES="$SOURCES -S $FILE" fi done - SPELL_ARGS="$SPELL_ARGS --name mkdocs $SOURCES" + SPELL_ARGS="$SPELL_ARGS --name docs $SOURCES" fi print "Running pyspelling..." From 8ca73146e1d42cab529952b9676b60761b7ab909 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 25 Mar 2026 16:44:35 +0100 Subject: [PATCH 5/8] update informacio --- docs/informacio.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/informacio.md b/docs/informacio.md index c6aaa6e..c83789d 100644 --- a/docs/informacio.md +++ b/docs/informacio.md @@ -31,7 +31,7 @@ Si trobeu alguna errada en el material, podeu comunicar-la mitjançant l'apartat ## :material-lightbulb-on-20: Suggeriments -Si voleu fer alguna suggerència o millora, podeu fer-ho mitjançant l'apartat +Si voleu fer alguna suggerència o proposta de millora, podeu fer-ho mitjançant l'apartat [__:octicons-comment-discussion-16: Debats al repositori de :material-github: GitHub__][Discussions]. [Discussions]: https://github.com/joapuiib/curs-git/discussions From 6953f0b690aebc5c086f3112a6d6bbdf7a1a1706 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 8 Apr 2026 19:47:17 +0200 Subject: [PATCH 6/8] properdocs in cicd examples --- docs/apunts/08_actions/exemples.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/apunts/08_actions/exemples.md b/docs/apunts/08_actions/exemples.md index 4ba9733..3204d1e 100644 --- a/docs/apunts/08_actions/exemples.md +++ b/docs/apunts/08_actions/exemples.md @@ -10,12 +10,12 @@ Per veure com combinar totes aquestes opcions, anem a veure diferents exemples d'automatitzacions en projectes de naturalesa distinta. -### Publicació d'un lloc web estàtic generat amb MkDocs a GitHub Pages +### Publicació d'un lloc web estàtic generat amb ProperDocs a GitHub Pages !!! success "Exemple en el repositori d'aquesta documentació: [`curs-git`][curs-git]" [curs-git]: {{ config.repo_url }} -La següent automatització permet __generar aquest lloc web__ amb [MkDocs][mkdocs] +La següent automatització permet __generar aquest lloc web__ amb [ProperDocs][properdocs] i __publicar-lo__ a [:octicons-browser-24: GitHub Pages][pages]. Aquesta acció s'executa sempre que es publiquen nous canvis sobre la branca `main`. També es pot executar manualment. @@ -27,7 +27,7 @@ Els passos que la componen són els següents: - Còpia els fitxers del repositori amb l'acció predefinida [`actions/checkout`][actions-checkout]. - Configura Python amb l'acció predefinida [`actions/setup-python`][actions-setup-python]. - Instal·la les dependències necessàries per executar MkDocs. - - Compila el lloc web amb l'ordre `mkdocs build`. + - Compila el lloc web amb l'ordre `properdocs build`. - Emmagatzema el directori amb la documentació generada (`site/`) com a artefacte per a la següent tasca amb l'acció predefinida [`actions/upload-pages-artifact`][actions-upload-pages-artifact]. 2. __Publica el lloc web a :octicons-browser-24: GitHub Pages.__ @@ -35,7 +35,7 @@ Els passos que la componen són els següents: - Publica l'artefacte generat en la tasca anterior l'acció predefinida [`actions/deploy-pages`][actions-deploy-pages]. -[mkdocs]: https://www.mkdocs.org/ +[properdocs]: https://www.properdocs.org/ [pages]: https://pages.github.com/ [actions-checkout]: https://github.com/marketplace/actions/checkout [actions-setup-python]: https://github.com/marketplace/actions/setup-python @@ -79,7 +79,7 @@ evitant així executar-la innecessàriament quan es modifiquen altres fitxers. ``` ### Execució de proves unitàries i d'integració en un projecte Java amb Maven -!!! example "Repositori d'exemple: [`tasklist-api`][tasklist-api]" +!!! success "Repositori d'exemple: [`tasklist-api`][tasklist-api]" Podeu observar el seu comportament en la :octicons-git-pull-request-16: Pull Request [feature: tasks can be marked as favorites (#1)][pr]. 1. En el :octicons-git-commit-16: commit [`2ca7024` – feature: tasks can be marked as favorites][pr-skip] no s'han executat les proves From bdf86d345a3e836ee30255c1e8e995c71f500586 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Wed, 8 Apr 2026 20:00:09 +0200 Subject: [PATCH 7/8] only use url snippens when building --- properdocs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/properdocs.yml b/properdocs.yml index 948b2dd..4c5d4e1 100644 --- a/properdocs.yml +++ b/properdocs.yml @@ -163,7 +163,7 @@ markdown_extensions: - pymdownx.mark - pymdownx.saneheaders - pymdownx.snippets: - url_download: true + url_download: !ENV [CI, false] - pymdownx.superfences: custom_fences: - name: mermaid From 520dd4751fd622341d71cf2b8848741bc7504141 Mon Sep 17 00:00:00 2001 From: Joan Puigcerver Date: Sun, 12 Apr 2026 17:34:08 +0200 Subject: [PATCH 8/8] update update-pages-artifact version --- .github/workflows/deploy.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 82dc30d..ce470ae 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -30,7 +30,7 @@ jobs: # Llista de tasques a executar - name: Build # Acció per compilar la documentació run: properdocs build --clean - name: Upload static files as artifact # Acció per pujar els fitxers estàtics com a artefacte - uses: actions/upload-pages-artifact@v4 + uses: actions/upload-pages-artifact@v5 with: path: ./site/ # Ruta dels fitxers estàtics generats per MkDocs