docs: Optional is False by default rather than True.

[FragmentedPacket]

The documentation advises that optional is true by default, but it's actually false.

[ogenstad]

We can't merge this as is. The reason is that attribute.mdx is a generated file (by invoke docs.generate), so this change needs to happen in the source location.

It also highlights the fact that the CI should have failed for this PR but doesn't as the job would have been filtered out. We need to change the CI to ensure that we run the job that executes invoke docs.validate if any of these files are changed. Currently this doesn't happen:

  validate-generated-documentation:
    if: |
      always() && !cancelled() &&
      !contains(needs.*.result, 'failure') &&
      !contains(needs.*.result, 'cancelled') &&
      needs.files-changed.outputs.python == 'true'
    needs: ["files-changed", "yaml-lint", "python-lint"]
    runs-on: "ubuntu-22.04"
    timeout-minutes: 5
    steps:
      - name: "Check out repository code"
        uses: "actions/checkout@v4"
        with:
          submodules: true
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: "Setup Python environment"
        run: |
          pipx install poetry
          poetry config virtualenvs.create true --local
          poetry env use 3.12
      - name: "Install dependencies"
        run: "poetry install --no-interaction --no-ansi"
      - name: "Setup environment"
        run: "pip install invoke toml"
      - name: "Validate generated documentation"
        run: "poetry run invoke docs.validate"

[BeArchiTek]

This file is auto-generated by invoke docs.generate, so your changes will be rewrite in the next generation.

[codspeed-hq]

CodSpeed Performance Report

Merging #5288 will degrade performances by 50.17%

_{Comparing FragmentedPacket:may-202412-docs-reference-schema-attribute-optional (1c8a013) with stable (4d32ce6)}

Summary

❌ 1 (👁 1) regressions
✅ 9 untouched benchmarks

Benchmarks breakdown

	Benchmark	stable	FragmentedPacket:may-202412-docs-reference-schema-attribute-optional	Change
👁	test_get_menu	236 ms	473.7 ms	-50.17%

[FragmentedPacket]

We can't merge this as is. The reason is that attribute.mdx is a generated file (by invoke docs.generate), so this change needs to happen in the source location.

It also highlights the fact that the CI should have failed for this PR but doesn't as the job would have been filtered out. We need to change the CI to ensure that we run the job that executes invoke docs.validate if any of these files are changed. Currently this doesn't happen:

  validate-generated-documentation:
    if: |
      always() && !cancelled() &&
      !contains(needs.*.result, 'failure') &&
      !contains(needs.*.result, 'cancelled') &&
      needs.files-changed.outputs.python == 'true'
    needs: ["files-changed", "yaml-lint", "python-lint"]
    runs-on: "ubuntu-22.04"
    timeout-minutes: 5
    steps:
      - name: "Check out repository code"
        uses: "actions/checkout@v4"
        with:
          submodules: true
      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: "Setup Python environment"
        run: |
          pipx install poetry
          poetry config virtualenvs.create true --local
          poetry env use 3.12
      - name: "Install dependencies"
        run: "poetry install --no-interaction --no-ansi"
      - name: "Setup environment"
        run: "pip install invoke toml"
      - name: "Validate generated documentation"
        run: "poetry run invoke docs.validate"

I believe I have this trigger correctly now. I tested this in https://github.com/opsmill/infrahub/actions/runs/12469863582/job/34803886595?pr=5288.

Addressed by adding doc file paths to be validated