feat: optional conf.py

[AlexanderLanin]

Motivation: 90-100% of users don't know how changes to conf.py affect documentation build. They assume they can just add code there. While this may be helpful for some quick fixes or workarounds, we need to discourage people from touching the file. As long as the file is there, people will touch it. So let's get rid of the file!

[github-actions]

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run --lockfile_mode=error //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.6.0) and connecting to it...
INFO: Invocation ID: 1a46ba70-2a19-464c-a601-2ffcb6c2d1d5
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
WARNING: Target pattern parsing failed.
ERROR: Skipping '//src:license-check': no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
ERROR: no such target '//src:license-check': target 'license-check' not declared in package 'src' defined by /home/runner/work/docs-as-code/docs-as-code/src/BUILD
INFO: Elapsed time: 6.521s
INFO: 0 processes.
ERROR: Build did NOT complete successfully
ERROR: Build failed. Not running target

[github-actions]

The created documentation from the pull request is available at: docu-html

[a-zw]

Could you use the bundle sources instead of globbing yourself again here?

[AlexanderLanin]

config.py is not included in the bundle sources

[Copilot]

Pull request overview

This PR makes conf.py optional for Bazel-driven Sphinx builds by generating a baseline Sphinx configuration from docs() macro attributes, and updates docs/tests to validate the new behavior.

Changes:

• Added project / project_url to docs() and implemented generated conf.py templating when no source conf.py exists.
• Updated runtime invocation to pass a generated config directory to Sphinx under bazel run.
• Expanded integration tests and documentation to cover “no conf.py” scenarios and the new macro parameters.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/tests/docs_bzl/test_missing_docs_config.py	New negative test asserting analysis fails when neither conf.py nor required macro values are provided
src/tests/docs_bzl/test_basic_docs.py	Adds a scenario build test for :needs_json without conf.py
src/tests/docs_bzl/scenarios/missing_docs_config/docs/index.rst	Adds scenario documentation content for missing-config fixture
src/tests/docs_bzl/scenarios/missing_docs_config/BUILD.negative	Adds negative BUILD fixture omitting project/project_url
src/tests/docs_bzl/scenarios/basic_docs/BUILD	Supplies project/project_url for a scenario that has no conf.py
src/incremental.py	Supports SPHINX_CONFIG_FILE to pass -c <dir> to Sphinx under bazel run
docs/reference/bazel_macros.rst	Documents optional conf.py and required project/project_url when absent
docs/how-to/setup.md	Updates setup instructions to make conf.py optional and recommend avoiding it
docs/conf.py	Removes the repository’s docs/conf.py
docs.bzl	Adds config generation rule, optional macro args, and uses generated config for needs_json; introduces docs alias for CLI
default_conf.py.tpl	Adds default generated Sphinx config template parameterized by project metadata
BUILD	Exports default_conf.py.tpl and sets project/project_url for the repo’s own docs() invocation

[github-actions]

Documentation preview for this pull request is available at:
pr-684: https://eclipse-score.github.io/docs-as-code/pr-684/

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated no new comments.

[a-zw]

Suggested change

tags = ["cli_help=Build documentation:\nbazel run //:docs"],

I believe this weird tag is just cargo-culting. I does not do anything, does it?

[AlexanderLanin]

we had a cli_help command. It's not cargo cult, as it was invented here. I just don't know if we still have it. Let's call it out of scope :-)