Any folder in docs by a-zw · Pull Request #431 · eclipse-score/docs-as-code

a-zw · 2026-03-03T15:11:20Z

📌 Description

A proposal for a mechanism how to include other directories of the repo into documentation.

🚨 Impact Analysis

This change does not violate any tool requirements and is covered by existing tool requirements
This change does not violate any design decisions
Otherwise I have created a ticket for new tool qualification

✅ Checklist

Added/updated documentation for new or changed features
Added/updated tests to cover the changes
Followed project coding standards and guidelines

github-actions · 2026-03-03T15:12:06Z

License Check Results

🚀 The license check job ran with the Bazel command:

bazel run //src:license-check

Status: ⚠️ Needs Review

Click to expand output

[License Check Output]
Extracting Bazel installation...
Starting local Bazel server (8.3.0) and connecting to it...
INFO: Invocation ID: 928de5d6-4970-4f31-b1b0-8c1a1c3a58ec
Computing main repo mapping: 
Computing main repo mapping: 
Computing main repo mapping: 
Loading: 
Loading: 0 packages loaded
Loading: 0 packages loaded
Loading: 0 packages loaded
    currently loading: src
Loading: 0 packages loaded
    currently loading: src
Analyzing: target //src:license-check (1 packages loaded)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)
Analyzing: target //src:license-check (1 packages loaded, 0 targets configured)

Analyzing: target //src:license-check (57 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (69 packages loaded, 9 targets configured)

Analyzing: target //src:license-check (89 packages loaded, 54 targets configured)

Analyzing: target //src:license-check (128 packages loaded, 1673 targets configured)

Analyzing: target //src:license-check (135 packages loaded, 2527 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (140 packages loaded, 2576 targets configured)

Analyzing: target //src:license-check (143 packages loaded, 4465 targets configured)

Analyzing: target //src:license-check (143 packages loaded, 4465 targets configured)

Analyzing: target //src:license-check (144 packages loaded, 4589 targets configured)

INFO: Analyzed target //src:license-check (145 packages loaded, 4715 targets configured).
[5 / 15] [Prepa] Creating source manifest for //src:license.check.license_check
[14 / 16] [Prepa] JavaToolchainCompileBootClasspath external/rules_java+/toolchains/platformclasspath.jar
INFO: Found 1 target...
Target //src:license.check.license_check up-to-date:
  bazel-bin/src/license.check.license_check
  bazel-bin/src/license.check.license_check.jar
INFO: Elapsed time: 24.478s, Critical Path: 2.65s
INFO: 16 processes: 12 internal, 3 processwrapper-sandbox, 1 worker.
INFO: Build completed successfully, 16 total actions
INFO: Running command line: bazel-bin/src/license.check.license_check src/formatted.txt <args omitted>
usage: org.eclipse.dash.licenses.cli.Main [-batch <int>] [-cd <url>]
       [-confidence <int>] [-ef <url>] [-excludeSources <sources>] [-help] [-lic
       <url>] [-project <shortname>] [-repo <url>] [-review] [-summary <file>]
       [-timeout <seconds>] [-token <token>]

github-actions · 2026-03-03T15:16:59Z

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

PiotrKorkus · 2026-03-04T09:34:06Z

Hello @a-zw,
thank you for that change that would be very helpful in reference_integration.

In my case the files I want to create a link to are generated during testing. In /docs static .rst files I would like to have a link to them. If testing was executed before and artifacts are in defined place the links should work. Otherwise I would expect docs build to be successful but the links to be broken.

Do you think it could work like this or some redesign is needed (around my idea or the tool itself)?

paulquiring

A needed addition to existing functionality.

docs/how-to/any_folder.rst

src/extensions/docs/index.rst

docs/how-to/any_folder.rst

a-zw · 2026-03-04T10:20:19Z

Hello @a-zw, thank you for that change that would be very helpful in reference_integration.

In my case the files I want to create a link to are generated during testing. In /docs static .rst files I would like to have a link to them. If testing was executed before and artifacts are in defined place the links should work. Otherwise I would expect docs build to be successful but the links to be broken.

Do you think it could work like this or some redesign is needed (around my idea or the tool itself)?

This approach is not suitable to include Bazel build artifacts/dependencies. That would be the next logical step to me though, because then we could stop using sphinx-collections in the docs-combo build.

@PiotrKorkus Are these test results integrated build artifacts though? Alternatively, are they "sources" committed to git? Or is it just temporary artifacts creating in some GH workflows?

PiotrKorkus · 2026-03-04T12:34:57Z

Hello @a-zw, thank you for that change that would be very helpful in reference_integration.
In my case the files I want to create a link to are generated during testing. In /docs static .rst files I would like to have a link to them. If testing was executed before and artifacts are in defined place the links should work. Otherwise I would expect docs build to be successful but the links to be broken.
Do you think it could work like this or some redesign is needed (around my idea or the tool itself)?

This approach is not suitable to include Bazel build artifacts/dependencies. That would be the next logical step to me though, because then we could stop using sphinx-collections in the docs-combo build.

@PiotrKorkus Are these test results integrated build artifacts though? Alternatively, are they "sources" committed to git? Or is it just temporary artifacts creating in some GH workflows?

Currently there are two cases:

static .md file that serves as template and is commited. CICD during test execution puts some some data in in
detailed coverage reports which are only temp artifacts in the workflow. I would like to add them to _build directory and create links in static .rst pages to them.

First option can also get rid of the template and use only temp artifact if possible.

a-zw · 2026-03-04T13:31:38Z

static .md file that serves as template and is commited. CICD during test execution puts some some data in in

detailed coverage reports which are only temp artifacts in the workflow. I would like to add them to _build directory and create links in static .rst pages to them.

First option can also get rid of the template and use only temp artifact if possible.

That sounds like there is already some scripting around both use cases anyways. Wouldn't it be easier to just extend these script a little and copy/symlink the stuff into docs/?

AlexanderLanin · 2026-03-05T09:48:49Z

Isn't this the same as sphinx-collections? Could you explain the relation / overlap?

a-zw · 2026-03-05T12:04:07Z

Isn't this the same as sphinx-collections? Could you explain the relation / overlap?

I addressed that within the documentation now.

The symlinks are quite confusing with git and gitignore does not seem like a suitable solution here.

MaximilianSoerenPollak · 2026-03-06T07:22:20Z

src/extensions/score_any_folder/__init__.py

+            logger.error(
+                "score_any_folder: source path must be relative, got: %r; skipping",
+                source_rel,
+            )
+            continue


Should this truly be an error then?
The build will be broken if thati s the case, that is wanted here I guess?

MaximilianSoerenPollak · 2026-03-06T07:24:28Z

src/extensions/score_any_folder/__init__.py

+def _create_symlinks(app: Sphinx) -> None:
+    created_links: set[Path] = set()
+
+    for source, link in _symlink_pairs(app):


Does this work?
You get a list[tuple[Path,Path]] back. But that list could have one or many tuples inside.
Will this actually unwrap each tuple inside it?
Or is the symlink_pairs function guranteed to only return 1 tuple?

MaximilianSoerenPollak · 2026-03-06T07:25:18Z

src/extensions/score_any_folder/__init__.py

+            logger.error(
+                "score_any_folder: target path already exists and is not a symlink: "
+                "%s; skipping",
+                link,
+            )


When would this be the case, and should it be an error?

MaximilianSoerenPollak · 2026-03-06T07:25:56Z

src/extensions/score_any_folder/__init__.py

+        created_links.add(link)
+        logger.debug("score_any_folder: created symlink %s -> %s", link, source)
+
+    setattr(app, _APP_ATTRIBUTE, created_links)


Is global _APP_ATTRIBUTE missing here in the function or does it work without?

MaximilianSoerenPollak · 2026-03-06T07:27:31Z

src/extensions/score_any_folder/tests/test_score_any_folder.py

+    make_sphinx_app: Callable[[dict[str, str]], SphinxTestApp], docs_dir: Path
+) -> None:
+    """An empty mapping produces no symlinks and no errors."""
+    make_sphinx_app({}).build()


Do you even need to build the app here?

MaximilianSoerenPollak · 2026-03-06T07:28:14Z

src/extensions/score_any_folder/tests/test_score_any_folder.py

+    make_sphinx_app({"../external": "notes"}).build()
+
+    assert not link.exists()


Guessing copy/paste error?

Seems to be duplicated from the lines above

MaximilianSoerenPollak

Overall makes sense and looks good.

Just couple of questions I had

github-project-automation bot added this to INF - Infrastructure Community Mar 3, 2026

github-project-automation bot moved this to Draft in INF - Infrastructure Community Mar 3, 2026

a-zw mentioned this pull request Mar 3, 2026

Make source_dir = "module root folder" possible #429

Open

paulquiring reviewed Mar 4, 2026

View reviewed changes

docs/how-to/any_folder.rst Outdated Show resolved Hide resolved

src/extensions/docs/index.rst Outdated Show resolved Hide resolved

docs/how-to/any_folder.rst Show resolved Hide resolved

paulquiring reviewed Mar 4, 2026

View reviewed changes

docs/how-to/any_folder.rst Show resolved Hide resolved

paulquiring mentioned this pull request Mar 5, 2026

Accept module root folder as docs source_dir #430

Closed

6 tasks

a-zw added 7 commits March 5, 2026 13:14

Add extension score_any_folder

8d68b99

Document any_folder extension

574e131

dogfooding any_folder extension

7a7faf9

Fix warnings

7c17326

Explain why not sphinx-collections

6986961

Cleanup symlinks after build

bc6884d

The symlinks are quite confusing with git and gitignore does not seem like a suitable solution here.

Review feedback

16e0160

a-zw force-pushed the any_folder_in_docs branch from d50c31c to 16e0160 Compare March 5, 2026 12:15

Fix pre-commit warnings

229e3e3

This was referenced Mar 5, 2026

Detailed coverage dashboard in docs-as-code pages eclipse-score/reference_integration#124

Open

Extra docs pages from artifacts eclipse-score/reference_integration#123

Open

Add copyright headers

87feae8

a-zw force-pushed the any_folder_in_docs branch from 9da0d52 to 87feae8 Compare March 5, 2026 14:34

a-zw marked this pull request as ready for review March 5, 2026 14:46

a-zw requested review from AlexanderLanin and MaximilianSoerenPollak as code owners March 5, 2026 14:46

a-zw requested review from dcalavrezo-qorix and nradakovic as code owners March 5, 2026 14:46

MaximilianSoerenPollak reviewed Mar 6, 2026

View reviewed changes

		make_sphinx_app({"../external": "notes"}).build()

		assert not link.exists()

Conversation

a-zw commented Mar 3, 2026

📌 Description

🚨 Impact Analysis

✅ Checklist

Uh oh!

github-actions bot commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

License Check Results

Uh oh!

github-actions bot commented Mar 3, 2026

Uh oh!

PiotrKorkus commented Mar 4, 2026

Uh oh!

paulquiring left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

a-zw commented Mar 4, 2026

Uh oh!

PiotrKorkus commented Mar 4, 2026

Uh oh!

a-zw commented Mar 4, 2026

Uh oh!

AlexanderLanin commented Mar 5, 2026

Uh oh!

a-zw commented Mar 5, 2026

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak Mar 6, 2026

Choose a reason for hiding this comment

Uh oh!

MaximilianSoerenPollak left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

github-actions bot commented Mar 3, 2026 •

edited

Loading