Merge pull request #129 from pedro-psb/merge-rewrite

[PULP-531] Merge rewrite-as-mkdocs feature branch

Author: pedro-psb

.github/workflows/build.yml

@@ -1,3 +1,4 @@
+---
 name: "Build"
 
 on:
@@ -11,7 +12,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v5"
         with:
-          python-version: "3.11"
+          python-version: "3.12"
       - name: "Install python dependencies"
         run: |
           pip install build setuptools wheel
@@ -25,3 +26,4 @@ jobs:
           path: |
             dist/
           if-no-files-found: "error"
+...

.github/workflows/docs-ci.yml

@@ -0,0 +1,70 @@
+---
+name: "Docs CI"
+
+on:
+  workflow_call:
+    inputs:
+      pulpdocs_ref:
+        description: "Git reference of this workflow file. Must match the one used for the workflow call"
+        type: string
+        required: true
+
+jobs:
+  build:
+    runs-on: "ubuntu-latest"
+    steps:
+      - name: "Checkout pulp-docs repository"
+        if: "${{ github.event.repository.name != 'pulp-docs' }}"
+        uses: "actions/checkout@v4"
+        with:
+          repository: "pulp/pulp-docs"
+          path: "pulp-docs"
+          ref: "${{ inputs.pulpdocs_ref }}"
+          fetch-depth: 0
+
+      - name: "Checkout component repository"
+        uses: "actions/checkout@v4"
+        with:
+          path: "${{ github.event.repository.name }}"
+          fetch-depth: 0
+
+      - name: "Instructions to run locally"
+        run: |
+          cat <<EOL
+          Ensure you have "pulp-docs" and "${{ github.event.repository.name }}" in your CWD with correct revisions:
+
+          git -C pulp-docs checkout "${{ inputs.pulpdocs_ref }}"
+          git -C ${{ github.event.repository.name }} checkout "${{ github.head_ref }}"
+
+          Then run:
+
+          cd pulp-docs
+          pulp-docs fetch --dest /tmp/pulp-docs-tmp
+          pulp-docs build --path pulp-docs@..:${{ github.event.repository.name }}@..:/tmp/pulp-docs-tmp
+          EOL
+
+      - uses: "actions/setup-python@v5"
+        with:
+          python-version: "3.12"
+
+      - name: "Install pulp-docs"
+        working-directory: "pulp-docs"
+        run: |
+          pip install --upgrade pip
+          pip install -r doc_requirements.txt
+
+      - name: "Build Docs"
+        working-directory: "pulp-docs"
+        env:
+          DOCS_PATH: "pulp-docs@..:${{ github.event.repository.name }}@.."
+          DOCS_TMPDIR: "/tmp/pulp-docs-tmp"
+        run: |
+          pulp-docs fetch --path-exclude "$DOCS_PATH" --dest "$DOCS_TMPDIR"
+          pulp-docs build --path "$DOCS_PATH:$DOCS_TMPDIR"
+
+      - name: "Sanity Check"
+        working-directory: "pulp-docs"
+        run: |
+          echo "Checking that the namespace for the component under CI exists in the built docs."
+          ls "site/${{ github.event.repository.name }}"
+...

.github/workflows/docs.yml

@@ -1,3 +1,4 @@
+---
 name: "pulp-docs CI"
 
 on:
@@ -8,16 +9,12 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
-  build:
-    uses: "./.github/workflows/build.yml"
-
   docs:
-    needs:
-      - "build"
-    uses: "./.github/workflows/docs.yml"
+    uses: "./.github/workflows/docs-ci.yml"
+    with:
+      pulpdocs_ref: "${{ github.head_ref }}"
 
   tests:
-    needs: "build"
     uses: "./.github/workflows/tests.yml"
 
   ready-to-ship:
@@ -33,3 +30,4 @@ jobs:
           echo '${{toJson(needs)}}' | jq -r 'to_entries[]|select(.value.result!="success")|.key + ": " + .value.result'
           echo '${{toJson(needs)}}' | jq -e 'to_entries|map(select(.value.result!="success"))|length == 0'
           echo "CI says: Looks good!"
+...

.github/workflows/pr.yml

@@ -1,3 +1,4 @@
+---
 name: "Tests"
 
 on:
@@ -11,7 +12,7 @@ jobs:
       - name: "Set up Python"
         uses: "actions/setup-python@v5"
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: "Install Test Dependencies"
         run: |
@@ -20,3 +21,4 @@ jobs:
       - name: "Run test suite"
         run: |
           pytest -sv
+...

.github/workflows/tests.yml

@@ -1,3 +1,4 @@
+---
 name: "Update Data Branch"
 
 on:
@@ -9,17 +10,17 @@ jobs:
   update-data:
     runs-on: "ubuntu-latest"
     permissions:
-      contents: write
+      contents: "write"
     steps:
       - name: "Checkout docs-data branch"
         uses: "actions/checkout@v4"
         with:
-          ref: docs-data
+          ref: "docs-data"
 
       - name: "Set up Python"
         uses: "actions/setup-python@v5"
         with:
-          python-version: "3.11"
+          python-version: "3.12"
 
       - name: "List requirements"
         run: |
@@ -40,3 +41,4 @@ jobs:
           git config user.name github-actions
           git config user.email [email protected]
           ./update-data.sh
+...

.github/workflows/update-data.yml

@@ -1,161 +1,15 @@
-tmp_dir/
 # Byte-compiled / optimized / DLL files
 __pycache__/
-*.py[cod]
-*$py.class
-
-# C extensions
-*.so
 
 # Distribution / packaging
-.Python
-build/
-develop-eggs/
 dist/
-downloads/
-eggs/
-.eggs/
-lib/
-lib64/
-parts/
-sdist/
-var/
-wheels/
-share/python-wheels/
 *.egg-info/
-.installed.cfg
-*.egg
-MANIFEST
-
-# PyInstaller
-#  Usually these files are written by a python script from a template
-#  before PyInstaller builds the exe, so as to inject date/other infos into it.
-*.manifest
-*.spec
 
-# Installer logs
-pip-log.txt
-pip-delete-this-directory.txt
-
-# Unit test / coverage reports
-htmlcov/
-.tox/
-.nox/
-.coverage
-.coverage.*
-.cache
-nosetests.xml
-coverage.xml
-*.cover
-*.py,cover
-.hypothesis/
+# Unit test
 .pytest_cache/
-cover/
-
-# Translations
-*.mo
-*.pot
-
-# Django stuff:
-*.log
-local_settings.py
-db.sqlite3
-db.sqlite3-journal
-
-# Flask stuff:
-instance/
-.webassets-cache
-
-# Scrapy stuff:
-.scrapy
-
-# Sphinx documentation
-docs/_build/
-
-# PyBuilder
-.pybuilder/
-target/
-
-# Jupyter Notebook
-.ipynb_checkpoints
-
-# IPython
-profile_default/
-ipython_config.py
-
-# pyenv
-#   For a library or package, you might want to ignore these files since the code is
-#   intended to run in multiple environments; otherwise, check them in:
-# .python-version
-
-# pipenv
-#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
-#   However, in case of collaboration, if having platform-specific dependencies or dependencies
-#   having no cross-platform support, pipenv may install dependencies that don't work, or not
-#   install all needed dependencies.
-#Pipfile.lock
-
-# poetry
-#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
-#   This is especially recommended for binary packages to ensure reproducibility, and is more
-#   commonly ignored for libraries.
-#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
-#poetry.lock
-
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/#use-with-ide
-.pdm.toml
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
-
-# Celery stuff
-celerybeat-schedule
-celerybeat.pid
-
-# SageMath parsed files
-*.sage.py
-
-# Environments
-.env
-.venv
-env/
-venv/
-ENV/
-env.bak/
-venv.bak/
-
-# Spyder project settings
-.spyderproject
-.spyproject
-
-# Rope project settings
-.ropeproject
 
 # mkdocs documentation
 /site
 
 # mypy
 .mypy_cache/
-.dmypy.json
-dmypy.json
-
-# Pyre type checker
-.pyre/
-
-# pytype static type analyzer
-.pytype/
-
-# Cython debug symbols
-cython_debug/
-
-# PyCharm
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/

.gitignore

@@ -2,6 +2,6 @@ build:
 	python -m build
 
 docs:
-	pulp-docs build
+	mkdocs build
 
-.PHONY: build docs
+.PHONY: docs build

Makefile

@@ -0,0 +1,27 @@
+{% extends "base.html" %}
+
+{% block styles %}
+{{ super() }}
+<link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+<style>
+  article.md-content__inner {margin: 0; padding: 0;}
+  article.md-content__inner::before {height: 0;}
+  div.md-main__inner {margin: 0;}
+  div.md-grid {max-width: none;}
+</style>
+{% endblock %}
+
+{% block site_nav %}
+{% endblock %}
+
+{% block content %}
+<redoc spec-url="../api.json"></redoc>
+{% endblock %}
+
+{% block scripts %}
+{{ super() }}
+<script src="https://cdn.jsdelivr.net/npm/redoc@next/bundles/redoc.standalone.js"></script>
+{% endblock %}
+
+{% block footer %}
+{% endblock %}