sphinx-needs 4.0.0__tar.gz → 4.2.0__tar.gz

sphinx_needs-4.2.0/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

sphinx_needs-4.2.0/.github/dependabot.yml

@@ -0,0 +1,19 @@
+# To get started with Dependabot version updates, you'll need to specify which
+# package ecosystems to update and where the package manifests are located.
+# Please see the documentation for all configuration options:
+# https://docs.github.com/github/administering-a-repository/configuration-options-for-dependency-updates
+
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    commit-message:
+      prefix: 🔧
+    schedule:
+      interval: monthly
+  - package-ecosystem: pip
+    directory: /
+    commit-message:
+      prefix: ⬆️
+    schedule:
+      interval: monthly

sphinx_needs-4.2.0/.github/scripts/extract_benchmark_data.py

@@ -0,0 +1,32 @@
+import json
+import sys
+
+
+def extract(input_file, output_file):
+    with open(input_file) as in_file:
+        input_data = json.load(in_file)
+
+    data = []
+
+    for bench in input_data["benchmarks"]:
+        name = bench["name"].split("[")[0]
+        if name == "test_basic_time":
+            name = "Small, basic Sphinx-Needs project"
+        elif name == "test_official_time":
+            name = "Official Sphinx-Needs documentation (without services)"
+
+        output = {
+            "name": name,
+            "unit": "s",
+            "value": bench["stats"]["mean"],
+            "extra": f"Commit: {input_data['commit_info']['id']}\nBranch: {input_data['commit_info']['branch']}\
+\nTime: {input_data['commit_info']['time']}",
+        }
+        data.append(output)
+
+    with open(output_file, "w") as out_file:
+        json.dump(data, out_file, sort_keys=True, indent=4)
+
+
+if "main" in __name__:
+    extract(sys.argv[1], sys.argv[2])

sphinx_needs-4.2.0/.github/workflows/benchmark.yaml

@@ -0,0 +1,62 @@
+name: Benchmark
+on:
+  push:
+    branches:
+      - master
+jobs:
+  benchmarks:
+    name: "Benchmark time & memory"
+    runs-on: "ubuntu-latest"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install dependencies
+        run: |
+          python -m pip install -e .[test,benchmark,docs]
+      - name: Run Benchmark for time
+        run: pytest --benchmark-json output.json -k _time tests/benchmarks
+
+      - name: Download previous benchmark data
+        uses: actions/cache@v4
+        with:
+          path: ./cache
+          key: ${{ runner.os }}-benchmark
+      - name: Extract benchmark data
+        run:  python .github/scripts/extract_benchmark_data.py output.json output_action.json
+      - name: Store benchmark result
+        uses: benchmark-action/github-action-benchmark@v1
+        with:
+          # What benchmark tool the output.txt came from
+          tool: 'customSmallerIsBetter'
+          # Where the output from the benchmark tool is stored
+          output-file-path: output_action.json
+          # Where the previous data file is stored
+          # external-data-json-path: ./cache/benchmark-data.json
+          # Workflow will fail when an alert happens
+          fail-on-alert: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          alert-threshold: '150%'
+          comment-on-alert: true
+          comment-always: false
+          auto-push: true
+          gh-pages-branch: "benchmarks"
+          benchmark-data-dir-path: "docs/bench"
+          alert-comment-cc-users: '@danwos'
+
+      - name: Run Benchmark for memory
+        run: pytest --benchmark-json output.json -k _memory tests/benchmarks
+      - name: Create memory flamegraph
+        run: memray flamegraph -o mem_out.html mem_out.bin
+      - name: Publish memory flamegraph
+        run: |
+          git checkout benchmarks
+          cp mem_out.html docs/memory.html
+          git add docs/memory.html
+          git -c "user.name=Sphinx-Needs CI" -c "user.email=ci@sphinx-needs.com" commit -m "memory.html update"
+      - name: Push changes   
+        run: git push origin benchmarks

sphinx_needs-4.2.0/.github/workflows/ci.yaml

@@ -0,0 +1,147 @@
+name: CI
+on:
+  push:
+    branches: [master]
+  pull_request:
+jobs:
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-20.04
+    steps:
+    - uses: actions/checkout@v4
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.9'
+    - uses: pre-commit/action@v3.0.1
+
+  tests-core:
+    name: "Core py${{ matrix.python-version }} sphinx~=${{ matrix.sphinx-version }} ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false  # Set on "false" to get the results of ALL builds
+      matrix:
+        os: ["ubuntu-latest"]
+        python-version: ["3.10", "3.12"]
+        sphinx-version: ["7.0", "8.0"]
+        include:
+          - os: "ubuntu-latest"
+            python-version: "3.9"
+            sphinx-version: "7.0"
+          - os: "windows-latest"
+            python-version: "3.9"
+            sphinx-version: "7.0"
+          - os: "windows-latest"
+            python-version: "3.12"
+            sphinx-version: "8.0"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install graphviz (linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get install graphviz
+      - name: Install graphviz (windows)
+        if: matrix.os == 'windows-latest'
+        run: choco install --no-progress graphviz
+      - name: Set Up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install dependencies
+        run: |
+          python -m pip install sphinx~=${{ matrix.sphinx-version }} -e .[test]
+          python -m pip freeze
+      - name: Run pytest
+        run: python -m pytest -v --ignore=tests/benchmarks -m "not jstest" --cov=sphinx_needs --cov-report=xml --cov-report=term-missing tests
+      - name: Create coverage
+        run: coverage xml
+      - name: Upload to Codecov
+        if: github.event.pull_request.head.repo.full_name == github.repository && github.repository == 'useblocks/sphinx-needs' && matrix.os == 'ubuntu-latest' && matrix.python-version == '3.10'
+        uses: codecov/codecov-action@v3
+        with:
+          token: ${{ secrets.CODECOV_TOKEN }}
+          name: sphinx-need-pytests
+          flags: pytests
+          file: ./coverage.xml
+          fail_ci_if_error: true
+
+  tests-js:
+    name: "JS py${{ matrix.python-version }} sphinx~=${{ matrix.sphinx-version }} ${{ matrix.os }}"
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        include:
+          - os: "ubuntu-latest"
+            python-version: "3.9"
+            sphinx-version: "7.0"
+          - os: "ubuntu-latest"
+            python-version: "3.12"
+            sphinx-version: "8.0"
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 18
+      - name: Install Cypress Test Framework
+        run: npm install cypress
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install dependencies
+        run: |
+          python -m pip install sphinx~=${{ matrix.sphinx-version }} -e .[test]
+          python -m pip freeze
+      - name: Run pytest
+        run: |
+          python -m pytest -v --ignore=tests/benchmarks -m "jstest" tests
+
+  tests-no-mpl:
+    name: Test matplotlib uninstalled
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install Dependencies
+        run: |
+          python -m pip install -e .[test,docs]
+          python -m pip uninstall -y matplotlib numpy
+          python -m pip freeze
+      - name: Run pytest
+        run: |
+          python -m pytest -v tests/no_mpl_tests.py
+      - name: Run HTML build
+        # the docs should build without matplotlib (just issuing warnings)
+        run: sphinx-build -b html . _build 
+        working-directory: docs
+
+  check:
+  
+    # This job does nothing and is only used for the branch protection
+    # see https://github.com/marketplace/actions/alls-green#why
+
+    if: always()
+
+    needs:
+    - lint
+    - tests-core
+    - tests-js
+    - tests-no-mpl
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Decide whether the needed jobs succeeded or failed
+      uses: re-actors/alls-green@release/v1
+      with:
+        jobs: ${{ toJSON(needs) }}

sphinx_needs-4.2.0/.github/workflows/docker.yaml

@@ -0,0 +1,77 @@
+name: Docker-Image
+
+on:
+  # Allow manual trigger
+  workflow_dispatch:
+    inputs:
+      # Ask if docker deployment needed when manually triggered
+      deploy:
+        description: 'Deploy Docker Image (y/n)?'
+        required: true
+        default: 'n'
+  push:
+    tags:
+      - '*.*.*'
+  pull_request:
+    paths: ['docker/**']
+
+env:
+  NEEDS_VERSION: 4.2.0
+  DEPLOY_IMAGE: ${{ github.event_name != 'pull_request' }}
+
+jobs:
+  build:
+    strategy:
+      fail-fast: ${{ github.event_name != 'pull_request' }}
+      matrix:
+        base-image: ["sphinxdoc/sphinx:latest", "sphinxdoc/sphinx-latexpdf:latest"]
+        image: ["sphinxneeds", "sphinxneeds-latexpdf"]
+        exclude:
+        - base-image: "sphinxdoc/sphinx:latest"
+          image: "sphinxneeds-latexpdf"
+        - base-image: "sphinxdoc/sphinx-latexpdf:latest"
+          image: "sphinxneeds"
+    name: "Image: ${{ matrix.image }} | Baseimage: ${{ matrix.base-image }}"
+    runs-on: ubuntu-latest
+    steps:
+      # Checks-out your repository under $GITHUB_WORKSPACE
+      - name: Checkout 🛎️
+        uses: actions/checkout@v4
+      -
+        name: Set up Docker Build 🐋
+        uses: docker/setup-buildx-action@v3
+      -
+        name: Extract metadata (tags, labels) for Docker
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ secrets.DOCKERHUB_USERNAME }}/${{ matrix.image }}
+          flavor: |
+            latest=true
+          tags: |
+            type=pep440,pattern={{version}}
+
+      - name: Check if deployment manually disabled
+        if: github.event.inputs.deploy == 'n'
+        run: |
+          echo "DEPLOY_IMAGE=false" >> "$GITHUB_ENV"
+
+      - name: Login to Docker Hub Docker Registry 🐸
+        uses: docker/login-action@v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Build and push html image to Doker Hub Docker Registry 🐳
+        id: docker_build
+        uses: docker/build-push-action@v5
+        with:
+          push: ${{ env.DEPLOY_IMAGE == 'true' }}
+          file: docker/Dockerfile
+          platforms: linux/amd64,linux/arm64
+          build-args: |
+            NEEDS_VERSION=${{ env.NEEDS_VERSION }}
+            BASE_IMAGE=${{ matrix.base-image }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

sphinx_needs-4.2.0/.github/workflows/docs.yaml

@@ -0,0 +1,22 @@
+name: Docs CI
+on:
+  pull_request:
+    paths: [docs/**]
+jobs:
+  linkcheck:
+    name: Docs-Linkcheck
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set Up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: Update pip
+        run: python -m pip install --upgrade pip
+      - name: Install Dependencies
+        run: |
+          python -m pip install -e .[docs]
+      - name: Run linkcheck
+        run: sphinx-build -b linkcheck . _build 
+        working-directory: docs

sphinx_needs-4.2.0/.github/workflows/js_test.yml

@@ -0,0 +1,50 @@
+name: Cypress E2E tests for Sphinx Needs
+on: [pull_request]
+jobs:
+  js_tests:
+    runs-on: ubuntu-latest
+    steps:
+    - name: Set Up Python 3.10.8
+      uses: actions/setup-python@v5
+      with:
+        python-version: 3.10.8
+    - name: Use Node.js
+      uses: actions/setup-node@v4
+      with:
+        node-version: 18
+    - uses: actions/checkout@v4
+    - name: Update pip
+      run: |
+        pip install -U wheel
+        pip install -U setuptools
+        python -m pip install -U pip
+    - name: Get pip cache dir
+      id: pip-cache
+      run: |
+        echo "dir=$(pip cache dir)" >> $GITHUB_OUTPUT
+    - name: Pip cache
+      uses: actions/cache@v4
+      with:
+        path: ${{ steps.pip-cache.outputs.dir }}
+        key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }}
+        restore-keys: |
+          ${{ runner.os }}-pip-
+    - name: Install package
+      run: |
+        pip install -e .[docs]
+    - name: Install Node dependencies
+      run: npm install cypress
+    - name: Build Docs
+      id: sphinx-build-docs
+      run: sphinx-build -a -T -E -j 4 -b html -d /tmp/sphinx_build/doctrees ./docs /tmp/sphinx_build/html
+    - name: E2E Cypress Test on Chrome
+      uses: cypress-io/github-action@v6
+      with:
+        browser: chrome
+        config-file: tests/js_test/cypress.config.js
+        start: npm start
+        # quote the url to be safe against YML parsing surprises
+        wait-on: 'http://localhost:8080'
+
+
+

sphinx_needs-4.2.0/.github/workflows/release.yaml

@@ -0,0 +1,27 @@
+name: Release
+on:
+  push:
+    tags:
+      - '[0-9].[0-9]+.[0-9]+'
+
+jobs:
+    publish:
+
+      name: Publish to PyPi
+      # needs: check
+      # if: github.event_name == 'push' && startsWith(github.event.ref, 'refs/tags')
+      runs-on: ubuntu-latest
+      steps:
+      - name: Checkout source
+        uses: actions/checkout@v4
+      - name: Set up Python 3.10
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.10"
+      - name: install flit
+        run: pip install flit~=3.4
+      - name: Build and publish
+        run: flit publish
+        env:
+          FLIT_USERNAME: __token__
+          FLIT_PASSWORD: ${{ secrets.PYPI }}

sphinx_needs-4.2.0/.gitignore

@@ -0,0 +1,42 @@
+.idea
+*.iml
+.DS_Store
+.venv*
+.pvenv
+.nox
+node_modules
+
+.envrc
+*.pyc
+*.egg-info
+*egg-info/
+dist
+build
+_build
+.cache/
+*pycache*
+.tox/
+.cache/
+.pytest_cache
+.coverage
+coverage.xml
+.doctrees
+docs/github_images/
+.eggs/
+
+
+.devcontainer/
+.vscode/
+.dockerignore
+
+.benchmarks/
+tests/cypress/
+cypress/
+
+output.json
+mem_out.*
+
+pyinstrument*
+*.prof
+
+uv.lock

sphinx_needs-4.2.0/.pre-commit-config.yaml

@@ -0,0 +1,44 @@
+repos:
+
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.6
+    hooks:
+    - id: ruff
+      args: [--fix]
+    - id: ruff-format
+
+  - repo: https://github.com/pre-commit/mirrors-mypy
+    rev: v1.14.1
+    hooks:
+    - id: mypy
+      files: sphinx_needs/.*
+      args: []
+      additional_dependencies:
+      - sphinx==7.4.7
+      - docutils==0.20
+      - types-docutils==0.20.0.20240201
+      - types-jsonschema
+      - types-requests
+
+  # TODO this does not work on pre-commit.ci
+  # - repo: https://github.com/astral-sh/uv-pre-commit
+  #   rev: 0.5.5
+  #   hooks:
+  #     - id: uv-lock  # Update the uv lockfile
+
+  - repo: local
+    hooks:
+      - id: check-readme
+        name: check-readme
+        files: README.rst
+        language: python
+        entry: rst2html.py README.rst --halt=warning
+        pass_filenames: false
+        additional_dependencies:
+        - docutils==0.20.1
+        - pygments

sphinx_needs-4.2.0/.readthedocs.yml

@@ -0,0 +1,30 @@
+version: 2
+
+sphinx:
+  configuration: docs/conf.py
+  builder: html
+  fail_on_warning: true
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs
+        - theme-furo
+
+build:
+  os: ubuntu-22.04
+  apt_packages:
+    - default-jdk
+    - graphviz
+  tools:
+    python: "3.11"
+  jobs:
+    pre_create_environment:
+      - echo "DOT details"
+      - which dot
+    pre_build:
+      # ideally we would just set the DOCS_THEME environment variable
+      # but I couldn't see an easy way to do that for the build job
+      - 'echo "furo" > docs/DOCS_THEME'

sphinx_needs-4.2.0/AUTHORS

@@ -0,0 +1,41 @@
+Maintainers
+-----------
+
+Daniel Woste <daniel@useblocks.com>
+
+Chris Sewell <chrisj_sewell@hotmail.com>
+
+Contributors
+------------
+
+Marco Heinemann <marco@useblocks.com>
+
+Trevor Lovett <trevor.lovett@gmail.com>
+
+Magnus Lööf <magnus.loof@gmail.com>
+
+Harri Kaimio
+
+Anders Thuné
+
+Daniel Eades <danieleades@hotmail.com>
+
+Philip Partsch <philip.partsch@googlemail.com>
+
+David Le Nir <david.lenir.e@thalesdigital.io>
+
+Baran Barış Yıldızlı <arisbbyil@gmail.com>
+
+Roberto Rötting <roberto.roetting@gmail.com>
+
+Nirmal Sasidharan <nirmal.sasidharan@de.bosch.com>
+
+Jacob Allen <jacob.allen@etas.com>
+
+Jörg Kreuzberger <j.kreuzberger@procitec.de>
+
+Duodu Randy <duodurandy19@gmail.com>
+
+Christian Wappler <chri.wapp@gmail.com>
+
+Simon Leiner <simon@leiner.me>