Merge pull request #12 from NewTec-GmbH/release/v1.1.x

Release v1.1.1
NewTec-GmbH · Oct 29, 2024 · a6e40ce · a6e40ce
2 parents 0bbdac3 + e34e534
commit a6e40ce
Show file tree

Hide file tree

Showing 5 changed files with 137 additions and 87 deletions.
diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml
@@ -67,7 +67,7 @@ jobs:
 
       - name: Deploy to GitHub Pages
         uses: peaceiris/actions-gh-pages@v4
-        if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+        if: ${{ github.event_name == 'release' }}
         with:
           publish_branch: gh-pages
           github_token: ${{ secrets.GITHUB_TOKEN }}

diff --git a/.vscode/tasks.json b/.vscode/tasks.json
@@ -4,7 +4,7 @@
     "version": "2.0.0",
     "tasks": [
         {
-            "label": "Python Requirements",
+            "label": "Install Python Requirements",
             "type": "shell",
             "command": [
                 "pip",
@@ -13,19 +13,19 @@
                 "requirements.txt"
             ],
             "group": {
-                "kind": "requirements"
+                "kind": "none"
             },
             "problemMatcher": []
         },
         {
-            "label": "NPM Requirements",
+            "label": "Install NPM Requirements",
             "type": "shell",
             "command": [
                 "npm",
                 "install"
             ],
             "group": {
-                "kind": "requirements"
+                "kind": "none"
             },
             "problemMatcher": []
         },
@@ -34,11 +34,11 @@
             "type": "shell",
             "dependsOrder": "sequence",
             "dependsOn": [
-                "Python Requirements",
-                "NPM Requirements"
+                "Install Python Requirements",
+                "Install NPM Requirements"
             ],
             "group": {
-                "kind": "requirements"
+                "kind": "none"
             },
             "problemMatcher": []
         },
@@ -71,7 +71,7 @@
                 "_build"
             ],
             "problemMatcher": []
-        }
+        },
         {
             "label": "Build and open",
             "type": "shell",

diff --git a/README.md b/README.md
@@ -4,6 +4,39 @@
 
 This is the documentation for the NewTec Git Work Instructions. You can find the resulting GitHub Pages in [here](https://newtec-gmbh.github.io/gitWorkInstructions/).
 
+## Build the documentation
+
+### Requirements
+
+* Node 20
+* Python 3.11
+
+### Instructions
+
+1. Clone the repository: `git clone https://github.com/NewTec-GmbH/gitWorkInstructions.git`
+2. Change directory: `cd gitWorkInstructions`
+3. Install Python dependencies: `pip install -r requirements.txt`
+4. Install Node dependencies: `npm install`
+5. Build the documentation: `sphinx-build doc _build --fail-on-warning`
+6. Open the documentation: `_build/index.html`
+
+### Visual Studio Code Tasks
+
+If you are using VSCode, the commands mentioned above are packed into tasks, making it easier for the developer to use.
+
+1. Clone the repository: `git clone https://github.com/NewTec-GmbH/gitWorkInstructions.git`
+2. Open the folder with VSCode: `code ./gitWorkInstructions`
+3. On the top menu, choose `Terminal` -> `Run Task...` and select the task you require.
+
+#### Available Tasks
+
+* Install Python Requirements
+* Install NPM Requirements
+* Install all requirements
+* Build
+* Clean
+* Build and open
+
 ## Used Libraries
 
 Used 3rd party libraries which are not part of the standard Python package:

diff --git a/doc/conf.py b/doc/conf.py
@@ -6,26 +6,30 @@
 
 import os.path
 import platform
+import subprocess
+git_version = subprocess.check_output(
+    ['git', 'describe', 'HEAD', '--tags', '--always'])
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
 project = "gitWorkInstructions"
 copyright = "2024 - present, NewTec GmbH"
 author = "NewTec GmbH"
-release = "1.1.0"
+release = git_version.decode()
+version = release  # Do not differenciate between release and version
 conf_py_path = "/doc/"  # with leading and trailing slashes
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
 extensions = [
-    "sphinxcontrib.mermaid",  # Mermaid diagrams
-    "sphinxcontrib.plantuml", # Plantuml diagrams
-    "myst_parser",            # MyST markdown parser
-    "sphinx_rtd_dark_mode",   # Dark mode
-    "sphinx_copybutton",      # Copy button
-    "sphinx_togglebutton"     # Toggle button
+    "sphinxcontrib.mermaid",   # Mermaid diagrams
+    "sphinxcontrib.plantuml",  # Plantuml diagrams
+    "myst_parser",             # MyST markdown parser
+    "sphinx_rtd_dark_mode",    # Dark mode
+    "sphinx_copybutton",       # Copy button
+    "sphinx_togglebutton"      # Toggle button
 ]
 
 templates_path = ["_templates"]
@@ -41,6 +45,9 @@
 # HTML theme and static files
 html_theme = "sphinx_rtd_theme"
 html_last_updated_fmt = "%b %d, %Y"
+html_theme_options = {
+    'style_external_links': True
+}
 
 html_static_path = ["_static"]
 html_css_files = [