diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml index 5e20721..ce470ae 100644 --- a/.github/workflows/deploy.yml +++ b/.github/workflows/deploy.yml @@ -28,9 +28,9 @@ 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@v4 + uses: actions/upload-pages-artifact@v5 with: path: ./site/ # Ruta dels fitxers estàtics generats per MkDocs diff --git a/.github/workflows/spellcheck.yml b/.github/workflows/spellcheck.yml index a1ed71f..808f9da 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: | @@ -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/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 diff --git a/docs/informacio.md b/docs/informacio.md index 75a2fb0..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 @@ -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/mkdocs.yml b/properdocs.yml similarity index 99% rename from mkdocs.yml rename to properdocs.yml index 948b2dd..4c5d4e1 100644 --- a/mkdocs.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 diff --git a/run.sh b/run.sh index 0f9a114..0a69d3e 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 - mkdocs $COMMAND $ARGS + $GENERATOR $COMMAND $ARGS else - CI=true mkdocs $COMMAND $ARGS + CI=true $GENERATOR $COMMAND $ARGS fi if [ $? -ne 0 ]; then print "Error building site." @@ -142,14 +144,13 @@ 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 SOURCES="$SOURCES -S $FILE" fi done - SPELL_ARGS="$SPELL_ARGS --name mkdocs $SOURCES" + SPELL_ARGS="$SPELL_ARGS --name docs $SOURCES" fi print "Running pyspelling..."