Clean up docs

.github/workflows/ci.yml

@@ -70,22 +70,6 @@ jobs:
           name: coverage-data
           path: ".coverage*"
 
-      - name: extract openapi schema
-        env:
-          DEPLOYMENT_TYPE: development
-          JWT_SECRET_KEY: 1234
-          DATA_DIR_ROOT: /tmp/fractal-server/
-          FRACTAL_TASKS_DIR: /tmp/fractal-server/tasks/
-          FRACTAL_RUNNER_WORKING_BASE_DIR: /tmp/fractal-server/artifacts/
-        run: poetry run fractalctl openapi
-
-      - name: Upload openapi schema
-        uses: actions/upload-artifact@v3
-        with:
-          name: openapi-schema
-          path: "openapi.json"
-
-
   coverage:
     name: Coverage
     runs-on: ubuntu-20.04
@@ -123,29 +107,3 @@ jobs:
           MINIMUM_ORANGE: 60
           ANNOTATE_MISSING_LINES: true
           ANNOTATION_TYPE: notice
-
-
-  docs:
-    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
-    name: Deploy docs
-    runs-on: ubuntu-latest
-    needs: coverage
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v3
-        with:
-          fetch-depth: 1
-          submodules: "recursive"
-
-      - name: Download openapi schema
-        uses: actions/download-artifact@v3
-        with:
-          name: openapi-schema
-          path: "docs/"
-
-      - name: Deploy docs
-        uses: mhausenblas/mkdocs-deploy-gh-pages@master
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          REQUIREMENTS: docs/doc-requirements.txt

.github/workflows/documentation.yaml

@@ -0,0 +1,76 @@
+name: docs
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+jobs:
+
+  docs:
+    name: "Deploy docs"
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/main' }}
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+          submodules: "recursive"
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: pip
+
+      - name: Install current fractal-server
+        run: python -m pip install -e .
+
+      - name: extract openapi schema
+        env:
+          DEPLOYMENT_TYPE: development
+          JWT_SECRET_KEY: 1234
+          FRACTAL_TASKS_DIR: /tmp/fractal-server/tasks/
+          FRACTAL_RUNNER_WORKING_BASE_DIR: /tmp/fractal-server/artifacts/
+        run: fractalctl openapi -f docs/openapi.json
+
+      - name: Deploy docs
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REQUIREMENTS: docs/doc-requirements.txt
+
+
+  docs-build:
+    name: "Test docs build"
+    runs-on: ubuntu-latest
+    if: ${{ github.event_name != 'push' || github.ref != 'refs/heads/main' }}
+
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 1
+          submodules: "recursive"
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: '3.10'
+          cache: pip
+
+      - name: Install current fractal-server
+        run: python -m pip install -e .
+
+      - name: extract openapi schema
+        env:
+          DEPLOYMENT_TYPE: development
+          JWT_SECRET_KEY: 1234
+          FRACTAL_TASKS_DIR: /tmp/fractal-server/tasks/
+          FRACTAL_RUNNER_WORKING_BASE_DIR: /tmp/fractal-server/artifacts/
+        run: fractalctl openapi -f docs/openapi.json
+
+      - name: Install dependencies
+        run: python -m pip install -r docs/doc-requirements.txt
+
+      - name: MKDocs build
+        run: mkdocs build --config-file mkdocs.yml

CHANGELOG.md

@@ -6,6 +6,7 @@
 * Improve handling of errors raised in `get_slurm_config` (\#800).
 * Clarify documentation about `SlurmConfig` (\#798).
 * Move `tests/test_common.py` into `fractal-common` repository (\#808).
+* Update documentation configuration and GitHub actions (\#811).
 
 # 1.3.4
 

docs/doc-requirements.txt

@@ -4,5 +4,4 @@ mkdocs-material
 mkdocs-gen-files
 mkdocs-literate-nav
 mkdocs-section-index
-mkdocs-coverage
 mkdocs-render-swagger-plugin

docs/extra.css

@@ -0,0 +1,17 @@
+/* Custom style for blockquotes */
+blockquote {
+  background-color: #ffffff; /* Light gray background */
+  border: 1px solid #000000; /* Black border */
+  padding: 10px;
+  margin: 20px 0;
+  border-radius: 4px;
+  font-size: 16px;
+  line-height: 1.6;
+  box-shadow: 2px 2px 5px rgba(0, 0, 0, 0.1); /* Optional: Add a subtle shadow */
+}
+
+/* Style the text inside blockquotes */
+blockquote p {
+  margin: 0;
+  color: #333; /* Dark text color */
+}

docs/install_and_deploy.md

@@ -133,8 +133,10 @@ gunicorn fractal_server.main:app --workers 2 --worker-class uvicorn.workers.Uvic
 
 ### Postgres setup
 
-TBD (see preliminary notes at https://github.com/fractal-analytics-platform/fractal-server/issues/388#issuecomment-1366713291)
+> See preliminary notes at<br>
+> https://github.com/fractal-analytics-platform/fractal-server/issues/388#issuecomment-1366713291.
 
 ### Fractal Server as a daemon/service
 
-TBD (see preliminary notes at https://github.com/fractal-analytics-platform/fractal-server/issues/388#issuecomment-1366719115).
+> See preliminary notes at<br>
+> https://github.com/fractal-analytics-platform/fractal-server/issues/388#issuecomment-1366719115.

mkdocs.yml

@@ -1,14 +1,10 @@
-site_name: Fractal Analytics Platform
+site_name: Fractal Server
 
 repo_url: https://github.com/fractal-analytics-platform/fractal-server
-repo_name: fractal-server@github
-
-extra_css:
-  - css/mkdocstrings.css
+repo_name: fractal-server
 
 markdown_extensions:
 - admonition
-  #- callouts
 - pymdownx.details
 - pymdownx.emoji
 - pymdownx.magiclink
@@ -25,22 +21,25 @@ theme:
   name: "material"
   custom_dir: "docs/overrides"
   features:
-  - content.code.annotate
+    - content.code.annotate
+    - content.code.copy
   palette:
   - media: "(prefers-color-scheme: light)"
     scheme: default
     primary: teal
-    accent: purple
+    accent: green
     toggle:
       icon: material/weather-sunny
       name: Switch to dark mode
   - media: "(prefers-color-scheme: dark)"
     scheme: slate
-    primary: black
-    accent: lime
+    primary: teal
+    accent: green
     toggle:
       icon: material/weather-night
       name: Switch to light mode
+  icon:
+    repo: fontawesome/brands/github
 
 nav:
   - Home page: index.md
@@ -66,10 +65,25 @@ plugins:
       nav_file: SUMMARY.md
   - section-index
   - mkdocstrings:
+      default_handler: python
       handlers:
         python:
           options:
             show_signature_annotations: false
             docstring_section_style: "table"
+            docstring_style: "google"
+            show_source: true
             filters: []
+            show_root_full_path: false
   - render_swagger
+
+extra_css:
+  - extra.css
+
+copyright: |
+  © Copyright 2022
+  Friedrich Miescher Institute for Biomedical Research and
+  University of Zurich
+  (see <u><a href="https://github.com/fractal-analytics-platform/fractal-server/blob/main/LICENSE">
+  LICENSE
+  </a></u>).