Merge pull request #5 from SFI-Visual-Intelligence/documentation

Added sphinx documentation with sample text, resolves #3

Author: sot176

.github/workflows/sphinx.yml

@@ -0,0 +1,41 @@
+name: Build documentation
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+permissions:
+  contents: write
+
+jobs:
+  docs:
+    runs-on: ubuntu-24.04
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+
+    - uses: mamba-org/setup-micromamba@v1
+      with:
+        micromamba-version: '2.0.5-0' # any version from https://github.com/mamba-org/micromamba-releases
+        environment-file: environment.yml
+        init-shell: bash
+        cache-environment: true
+        post-cleanup: 'all'
+        generate-run-shell: false
+
+    - name: Sphinx build
+      run: |
+        sphinx-build doc _build
+      shell: bash -el {0}
+
+    - name: Deploy to GitHub Pages
+      uses: peaceiris/actions-gh-pages@v4
+      if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+      with:
+        publish_branch: gh-pages
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        publish_dir: _build/
+        force_orphan: true

.gitignore

@@ -0,0 +1,4 @@
+Data/
+Results/
+Experiments/
+_build/

doc/about.md

@@ -0,0 +1,3 @@
+# About this code
+
+Work in progress ...

doc/conf.py

@@ -0,0 +1,16 @@
+project = "Collaborative Coding Exam"
+copyright = "2025, SFI Visual Intelligence"
+author = "SFI Visual Intelligence"
+release = "0.0.1"
+
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+extensions = [
+    "myst_parser",  # in order to use markdown
+]
+
+myst_enable_extensions = [
+    "colon_fence",  # ::: can be used instead of ``` for better rendering
+]
+
+html_theme = "sphinx_rtd_theme"

doc/index.md

@@ -0,0 +1,15 @@
+# Our code documentation
+
+Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
+incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
+nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
+Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
+fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
+culpa qui officia deserunt mollit anim id est laborum.
+
+:::{toctree}
+:maxdepth: 2
+:caption: Some caption
+
+about.md
+:::

environment.yml

@@ -0,0 +1,12 @@
+name: cc-exam
+channels:
+  - defaults
+dependencies:
+  - python=3.12
+  - myst-parser
+  - sphinx
+  - sphinx-autoapi
+  - sphinx-autobuild
+  - sphinx-rtd-theme
+  - pip
+prefix: /opt/miniconda3/envs/cc-exam