Skip to content

chore: build docs from single-source community files #1005

Merged
lschilders merged 6 commits into
mainfrom
chore/dry-community-health-files
Jun 25, 2026
Merged

chore: build docs from single-source community files #1005
lschilders merged 6 commits into
mainfrom
chore/dry-community-health-files

Conversation

@lschilders

Copy link
Copy Markdown
Collaborator

This pull request streamlines how community documents (like the Code of Conduct and Contributing Guide) are integrated into the documentation and improves cross-referencing and navigation within the docs. The main changes involve removing duplicated Markdown files from the repository, updating the Sphinx configuration to better handle included Markdown, and simplifying the documentation source files to include the community files from a single source of truth.

Community file management and documentation integration:

  • Removed the duplicated .github/CODE_OF_CONDUCT.md and .github/CONTRIBUTING.md files from the repository, ensuring these are now materialized into the docs at build time from the org-level OpenSTEF/.github repository, and included in the documentation via the _community/ directory. [1] [2]
  • Updated docs/source/contribute/code_of_conduct.rst and docs/source/contribute/contributing_guide.rst to include the respective Markdown files from _community/ using the MyST parser, rather than maintaining separate RST content. [1] [2]

Sphinx documentation build improvements:

  • Added and configured the sphinx.ext.autosectionlabel extension in docs/source/conf.py to automatically generate unique cross-reference labels for every section heading, making it easier to deep-link into included Markdown documents. Also, configured Sphinx to suppress duplicate label warnings and to exclude _community/ files from source discovery. [1] [2] [3]
  • Enabled automatic anchor generation for Markdown headings (h1-h4) with myst_heading_anchors = 4 in docs/source/conf.py, ensuring intra-page links in included Markdown files work as expected.

Documentation navigation and linking updates:

  • Updated links in docs/source/contribute/index.rst to use the new autosectionlabel-prefixed section references, ensuring that navigation cards and references point to the correct sections in the included community documents. [1] [2]

Signed-off-by: Lars Schilders <lars.schilders@alliander.com>
Signed-off-by: Lars Schilders <lars.schilders@alliander.com>
@lschilders lschilders requested a review from a team June 25, 2026 12:24
@github-actions github-actions Bot added the chore Improvements or additions to documentation label Jun 25, 2026
egordm
egordm previously approved these changes Jun 25, 2026

@egordm egordm left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looks good. Maybe recheck if files already exist would be nice. Otherwise approved.

Signed-off-by: Lars Schilders <lars.schilders@alliander.com>
@sonarqubecloud

Copy link
Copy Markdown

@lschilders lschilders merged commit 5789439 into main Jun 25, 2026
5 checks passed
@lschilders lschilders deleted the chore/dry-community-health-files branch June 25, 2026 14:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

chore Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants