Add markdownlint pre-commit hooks, Build PRs on readthedocs

[mmaclay]

This pull request introduces several improvements to documentation quality control, developer workflow automation, and markdown/YAML linting. The main changes are the addition of new configuration files and enhancements to CI workflows, ensuring that documentation and configuration files are consistently linted, validated, and built successfully on every pull request. Minor improvements to documentation formatting are also included.

CI/CD and Automation Enhancements:

• Added a new GitHub Actions workflow (.github/workflows/docs.yml) to automatically build Sphinx documentation on pull requests, treating warnings as errors and enabling nitpicky mode for strict reference checking.
• Updated the main test workflow (.github/workflows/test.yml) to improve matrix job naming, expand trigger types, prevent fail-fast on matrix failures, and upgrade actions to their latest major versions. Poetry installation is now handled via pip for consistency. [1] [2]

Linting and Pre-commit Hook Improvements:

• Introduced a comprehensive .pre-commit-config.yaml that adds hooks for markdown linting (markdownlint), reStructuredText validation (rstcheck), YAML linting (yamllint), spell checking (codespell), and several general file hygiene checks.
• Added .markdownlint.yaml and .yamllint.yaml configuration files to enforce repository-specific markdown and YAML style rules, mirroring existing conventions and ensuring consistency across tools. [1] [2]

Documentation and Formatting Improvements:

• Markdownlint formatting, including better list formatting and section spacing in citing_and_publishing_datasets.md and improved heading levels in digital_object_identifiers.md. [1] [2] [3] [4] [5] [6] [7]
• Enabled heading anchors for H1–H3 in the Sphinx configuration (docs/source/conf.py) to improve linkability of documentation sections.
• Added the data_management page to the main data management toctree for improved navigation.

[Copilot]

Pull request overview

This PR strengthens documentation quality gates and contributor workflow automation by adding CI checks for Sphinx builds and introducing standardized linting/spellcheck tooling via pre-commit, alongside markdown/rst formatting cleanups across the docs.

Changes:

• Added a dedicated GitHub Actions workflow to build Sphinx docs on PRs with strict warning/reference checking.
• Expanded/modernized dependency-check CI and introduced comprehensive pre-commit hooks (Markdown, RST, YAML, codespell, hygiene).
• Reformatted multiple documentation pages for consistent headings, lists, and code fences; improved Sphinx anchor/linkability.

Reviewed changes

Copilot reviewed 23 out of 32 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
pyproject.toml	Aligns codespell ignore list with pre-commit usage.
docs/source/workflows/open_source/pull_requests.md	Markdown heading/list formatting for lint compliance.
docs/source/workflows/open_source/index.rst	Minor toctree formatting normalization.
docs/source/workflows/open_source/code_of_conduct.md	Wrapped long lines / list formatting for consistency.
docs/source/workflows/jenkins_job_builder/index.rst	Simplifies JJB toctree entries to match current pages.
docs/source/workflows/index.rst	Adds JJB section into main workflows toctree.
docs/source/workflows/generative_ai_tools/index.rst	Minor toctree formatting normalization.
docs/source/workflows/generative_ai_tools/generative_ai_tools_at_lasp.md	Removes an internal link and normalizes formatting.
docs/source/workflows/docker/index.rst	Removes JJB from Docker section and normalizes formatting.
docs/source/workflows/docker/developing_in_devcontainers.md	Removes extra blank lines for markdownlint compliance.
docs/source/workflows/docker/beginner_guide_to_docker.md	Adds explicit code fence language.
docs/source/workflows/docker/advanced_guide_to_docker.md	Adds explicit code fence language and removes trailing blank line.
docs/source/programming_languages/python/packaging_and_distribution.md	Fixes inline-code formatting and internal anchors.
docs/source/programming_languages/python/best_practices.md	Fixes inline-code formatting.
docs/source/how_to_write_docs.md	Wraps lists/paragraphs for lint compliance.
docs/source/data_management/index.rst	Adds data_management page to toctree; normalizes formatting.
docs/source/data_management/file_formats/index.rst	Minor toctree formatting normalization.
docs/source/data_management/digital_object_identifiers.md	Heading level normalization + spacing fixes.
docs/source/data_management/citing_and_publishing_datasets.md	List wrapping/spacing fixes for markdownlint compliance.
docs/source/conf.py	Enables MyST heading anchors (H1–H3) for stable section links.
docs/README.md	Minor formatting normalization.
LICENSE	Minor formatting normalization (newline).
CODE_OF_CONDUCT.md	Minor formatting normalization (newline).
.yamllint.yaml	Introduces repo yamllint configuration.
.readthedocs.yaml	Makes RTD fail on Sphinx warnings and normalizes indentation.
.pre-commit-config.yaml	Adds/expands pre-commit hooks and enables pre-commit.ci autofix.
.mdlrc	Minor formatting normalization.
.mdl_style.rb	Minor formatting normalization.
.markdownlint.yaml	Introduces markdownlint-cli config aligned with existing mdl style.
.gitignore	Minor formatting normalization.
.github/workflows/test.yml	Updates actions versions, improves matrix config, installs Poetry via pip, and expands triggers.
.github/workflows/docs.yml	Adds PR docs build workflow with strict Sphinx settings and job summary output.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[vmartinez-cu]

Many files were updated as part of this work. Was this done automatically due to the linting and pre-commit hook updates?

[mmaclay]

Many files were updated as part of this work. Was this done automatically due to the linting and pre-commit hook updates?

@vmartinez-cu Yes! I added markdownlint and yamllint and that basically automatically enforced a bunch of changes (line length, indentations for lists, spacing, not jumping from a # title to a ### sub heading etc). We might want to turn off some of those rules if we think it's too rigid, but I do appreciate the consistency as well as it finding pages/files that were not listed in the index.rst

I'm going to update the readme.md a bit so it's clear how to run precommit and contribute with the changes.

[vmartinez-cu]

Consistency is nice and the sanity check is super helpful. Thanks for adding these improvements!

[Copilot]

Pull request overview

Copilot reviewed 27 out of 36 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.