Porting guide modernization

Jenkinsfile

@@ -2,6 +2,7 @@ pipeline {
     agent {
         docker {
             image "python:3.12"
+            args '-u root:root'  // Run as root to allow package installation
         }
     }
     options {
@@ -19,6 +20,19 @@ pipeline {
                 sh 'pip install --quiet --no-cache-dir --user --upgrade -r requirements.txt'
             }
         }
+        stage("Setup Mermaid") {
+            steps {
+                script {
+                    try {
+                        def setup = load 'Jenkinsfile.setup-mermaid'
+                        setup.call()
+                    } catch (Exception e) {
+                        echo "Setup Mermaid failed with error: ${e.getMessage()}"
+                        throw e
+                    }
+                }
+            }
+        }
         stage("Build docs"){
             steps {
                 sh 'python3 -m sphinx -Wab html . _build/html/'
@@ -29,9 +43,13 @@ pipeline {
         stage('Fix git ref for non-master builds') {
             when { not { branch 'master' }  }
             steps {
-                // Workaround to create the master branch since Jenkins
-                // refuses to do it on PR builds
-                sh 'git show-ref --verify --quiet master || git branch master `git show-ref -s origin/master`'
+                sh '''
+                    # Add workspace to safe.directory
+                    git config --global --add safe.directory "${WORKSPACE}"
+
+                    # Original command
+                    git show-ref --verify --quiet master || git branch master `git show-ref -s origin/master`
+                '''
             }
         }
         stage('Check redirects') {
@@ -45,4 +63,4 @@ pipeline {
             cleanWs()
         }
     }
-}
+}

Jenkinsfile.setup-mermaid

@@ -0,0 +1,39 @@
+def call() {
+    sh '''
+        set -x
+        set -e
+
+        echo "Adding NodeSource repository..."
+        curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
+
+        echo "Updating package lists..."
+        apt-get update
+
+        echo "Installing Node.js..."
+        apt-get install -y nodejs
+
+        echo "Installing Chrome dependencies..."
+        apt-get install -y ca-certificates fonts-liberation libasound2 libatk-bridge2.0-0 \
+            libatk1.0-0 libc6 libcairo2 libcups2 libdbus-1-3 libexpat1 libfontconfig1 \
+            libgbm1 libglib2.0-0 libgtk-3-0 libnspr4 libnss3 libpango-1.0-0 \
+            libpangocairo-1.0-0 libstdc++6 libx11-6 libx11-xcb1 libxcb1 libxcomposite1 \
+            libxcursor1 libxdamage1 libxext6 libxfixes3 libxi6 libxrandr2 libxrender1 \
+            libxss1 libxtst6 wget xdg-utils
+
+        echo "Installing mermaid-cli..."
+        npm install -g @mermaid-js/mermaid-cli
+
+        echo "Installing Chrome headless shell..."
+        npx puppeteer browsers install chrome-headless-shell
+
+        echo "Configuring Puppeteer to run with --no-sandbox..."
+        mkdir -p /root/.config
+        echo '{
+            "args": ["--no-sandbox"]
+        }' > /root/.config/mmdc-config.json
+
+        echo "Setup completed successfully"
+    '''
+}
+
+return this

conf.py

@@ -32,9 +32,15 @@
 # ones.
 extensions = [
     'sphinx.ext.todo',
-    'sphinxext.rediraffe'
+    'sphinxext.rediraffe',
+    'sphinxcontrib.mermaid'
 ]
 
+# Mermaid configuration for static image generation
+mermaid_output_format = 'svg'
+mermaid_cmd = 'mmdc -p /root/.config/mmdc-config.json'
+mermaid_verbose = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

index.rst

@@ -7,7 +7,7 @@ Welcome to the official documentation of the UBports project!
 
 UBports develops the mobile phone operating system Ubuntu Touch. Ubuntu Touch is a mobile operating system focused on ease of use, privacy, and convergence.
 
-On this website you find guides to :doc:`install Ubuntu Touch on your mobile phone <userguide/install>`, :doc:`use Ubuntu Touch <userguide/dailyuse/index>`, :doc:`develop Ubuntu Touch apps <appdev/index>`, :doc:`port Ubuntu Touch to an Android handset <porting/introduction/index>` and :doc:`learn more about system components <systemdev/index>`. If this is your first time here, please consider reading our :doc:`introduction <about/introduction>`.
+On this website you find guides to :doc:`install Ubuntu Touch on your mobile phone <userguide/install>`, :doc:`use Ubuntu Touch <userguide/dailyuse/index>`, :doc:`develop Ubuntu Touch apps <appdev/index>`, :doc:`port Ubuntu Touch to an Android handset <porting/index>` and :doc:`learn more about system components <systemdev/index>`. If this is your first time here, please consider reading our :doc:`introduction <about/introduction>`.
 
 If you want to help improving this documentation, :doc:`the Documentation contribute page <contribute/documentation>` will get you started.
 
@@ -67,11 +67,16 @@ You may view this documentation in the following languages:
    :caption: Porting
    :name: sec-porting
 
-   porting/introduction/index.rst
-   porting/build_and_boot/index.rst
-   porting/configure_test_fix/index.rst
-   porting/finalize/index.rst
-   porting/UpdatePortsFor2004.rst
+   porting/index.rst
+   porting/fundamentals/index
+   porting/quick-start/index
+   porting/preparation/index
+   porting/modern-porting/index
+   porting/debugging/index
+   porting/finalize/index
+   porting/vendor-specific/index
+   porting/legacy-porting/index
+   porting/resources/index
 
 .. toctree::
    :maxdepth: 1

porting/README.md

@@ -0,0 +1,65 @@
+# Ubuntu Touch Porting Guide Development
+
+This repository contains the development version of the modernized Ubuntu Touch porting guide.
+The guide is being reworked by Ari Börde Kröyer, based on the current guide and the Halium Generic 
+Adaptation Build Tools, and using AI assistance. 
+
+# Notes to the Reader
+
+My end goal is that this version of the guide can become a drop-in replacement for the current
+version of the guide, and serve to help and promote the porting effort. This will require a 
+coordinated community effort, as I am not sufficiently technically knowledgeable and skilled to 
+complete this task on my own.
+
+I therefore ask the reader to keep in mind that what you are seeing is an unfinished product which
+may very well contain factual mistakes and errors, and that your ideas and feedback are both welcome 
+and needed.
+
+I am making the first version available on November 21, 2024. In an early phase, I encourage readers 
+to discuss this project on Telegram, in the UBports Porting group (https://t.me/ubports_porting). Feel 
+free to tag me there when proposing ideas, pointing out errors, etc. Please keep in mind that I have
+limited time to spend on this project, so my responses might come with some delay.
+
+
+## Setup Instructions
+
+1. Install dependencies:
+```bash
+pip install sphinx furo sphinxext-rediraffe sphinxcontrib-mermaid
+```
+
+2. Clone the repository:
+```bash
+git clone https://github.com/abkro/docs.ubports.com porting-guide/
+cd porting-guide
+```
+
+3. Build the documentation:
+```bash
+cd porting-guide-work
+make html
+```
+
+4. View the documentation:
+- In the `porting-guide-work/` folder, find and open `_build/html/index.html` in your web browser
+- Navigate through sections using the sidebar
+
+## Review Guidelines
+
+Please review:
+- Technical accuracy
+- Clarity of instructions
+- Logical flow between sections
+- Completeness of each section
+- Cross-references and navigation
+
+Submit feedback through:
+- Telegram, in the UBports Porting group (https://t.me/ubports_porting)
+
+## Building Troubleshooting
+
+If you encounter build errors:
+- Ensure all dependencies are installed
+- Check Python version (3.6+ required)
+- Verify directory structure matches repository
+- Check console output for specific error messages

porting/_static/css/ubports.css

@@ -0,0 +1,4 @@
+.parameter-details {
+    margin-left: 2em;
+    margin-bottom: 2em;
+}