docs: explain dependency marker shorthands

[Mohamedajab]

Resolves: #9183

Documents the Poetry-specific python and platform dependency shorthands, explains when to use markers, and clarifies that restrictions supplied through multiple properties are combined with and. It also distinguishes [tool.poetry.dependencies] shorthand syntax from standard PEP 508 markers in [project.dependencies].

• Added tests for changed code. (Not applicable: documentation-only change.)
• Updated documentation for changed code.

Validation: all configured pre-commit hooks passed for docs/dependency-specification.md.

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="docs/dependency-specification.md" line_range="610" />
<code_context>
+
+This installs `example` only when all three restrictions match. The shorthand
+properties are specific to `[tool.poetry.dependencies]`; dependencies in
+`[project.dependencies]` use standard PEP 508 marker expressions instead.
+
 ### `extra` environment marker
</code_context>
<issue_to_address>
**nitpick:** The documentation refers to `[project.dependencies]` as a dependency section, but PEP 621 dependencies are declared as the `dependencies` key inside the `[project]` table; `[project.dependencies]` is not a valid section for this syntax. Readers who follow this wording can create an invalid or ignored configuration.

**Suggested fix:** Replace `[project.dependencies]` with `[project]` and clarify that its `dependencies` array uses PEP 508 marker expressions.
</issue_to_address>

Sourcery assessment

Approved.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[sourcery-ai]

Sourcery assessment

Approved.

[dimbleby]

Explain why not #10952

[Mohamedajab]

You're right - #10952 already covers #9183 and is more complete, including the raw sys.platform guidance and explicit marker equivalences. I missed the existing PR when picking this up, so there is no good reason to duplicate that work. Closing this in favour of #10952. Sorry for the noise.