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.

[Copilot]

Pull request overview

Copilot reviewed 28 out of 37 changed files in this pull request and generated 5 comments.

---

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

[Copilot]

Docs workflow uses Python 3.11, but ReadTheDocs is configured for Python 3.10. This can lead to "passes in GitHub Actions, fails on RTD" (or vice-versa) if a dependency or Sphinx behavior differs across Python versions. Consider aligning the Python version between docs.yml and .readthedocs.yaml (or explicitly testing both).

Suggested change

	python-version: '3.11'
	python-version: '3.10'

[Copilot]

Poetry is installed unpinned via pip install poetry. That means CI behavior can change when a new Poetry release ships (including lock/install semantics), making builds less reproducible. Consider pinning Poetry to a specific version (and bumping it intentionally) or installing from a constraints/requirements file.

Suggested change

	run: python -m pip install poetry
	run: python -m pip install "poetry==1.8.3"

[Copilot]

markdownlint-cli2 is pinned to v0.19.1, but newer releases are available (e.g., v0.22.0). Bumping the rev periodically helps pick up rule fixes and bug/security patches (especially since this hook runs on every commit/PR).

Suggested change

	rev: v0.19.1
	rev: v0.22.0

[Copilot]

"ORCiDs" is not the standard spelling/branding for ORCID identifiers (commonly "ORCID iDs" or "ORCIDs"). Since this heading is user-facing and appears in navigation/anchors, consider updating it to the standard form.

Suggested change

	### [ORCiDs](https://orcid.org/)
	ORCiDs are like DOIs but provide
	persistent digital object identifiers for people.
	### [ORCID iDs](https://orcid.org/)
	ORCID iDs are like DOIs but provide
	persistent digital identifiers for researchers.

[Copilot]

The new "out of scope" rule says not to include links/references to LASP internal resources, but this README still points readers to an internal Slack channel, and the docs currently contain other internal links (e.g., Confluence/Jira). Consider clarifying the rule (e.g., internal URLs vs internal communication channels, or apply the rule only to new content) so contributors know what’s expected.

Suggested change

	* Do not include links or references to LASP internal resources
	* Do not include any material that is considered Controlled Unclassified Information (CUI)
	* Do not include informal meeting notes
	* Do not include links or URLs to LASP internal resources (e.g., Confluence, Jira, internal Slack workspaces) in the published guide
	* Do not include any material that is considered Controlled Unclassified Information (CUI)
	* Do not include informal meeting notes
	These restrictions apply to new or updated content. High-level mentions of internal communication channels (such as a Slack channel name, without a URL) are acceptable for contributor guidance but should not appear in end-user documentation.