Merge pull request #2530 from rohitshinde08/issue/2526

Fix broken relative links in README and CHANGELOG for both GitHub and Sphinx

Author: DanielNoord

.gitignore

@@ -78,3 +78,4 @@ pyvenv.cfg
 
 # Sphinx documentation build
 docs/_build/
+docs/generated/

CHANGELOG.md

@@ -2,7 +2,7 @@ Changelog
 =========
 
 NOTE: isort follows the [semver](https://semver.org/) versioning standard.
-Find out more about isort's release policy [here](../docs/major_releases/release_policy.md).
+Find out more about isort's release policy [here](docs/major_releases/release_policy.md).
 
 ## Releases
 

README.md

@@ -27,9 +27,9 @@ editors](https://github.com/pycqa/isort/wiki/isort-Plugins) to
 quickly sort all your imports. It requires Python 3.10+ to run but
 supports formatting Python 2 code too.
 
-- [Try isort now from your browser!](../docs/quick_start/0.-try.md)
-- [Using black? See the isort and black compatibility guide.](../docs/configuration/black_compatibility.md)
-- [isort has official support for pre-commit!](../docs/configuration/pre-commit.md)
+- [Try isort now from your browser!](docs/quick_start/0.-try.md)
+- [Using black? See the isort and black compatibility guide.](docs/configuration/black_compatibility.md)
+- [isort has official support for pre-commit!](docs/configuration/pre-commit.md)
 
 ![Example Usage](https://raw.github.com/pycqa/isort/main/example.gif)
 
@@ -151,7 +151,7 @@ notified.
 
 You will notice above the \"multi\_line\_output\" setting. This setting
 defines how from imports wrap when they extend past the line\_length
-limit and has [12 possible settings](../docs/configuration/multi_line_output_modes.md).
+limit and has [12 possible settings](docs/configuration/multi_line_output_modes.md).
 
 ## Indentation
 
@@ -204,7 +204,7 @@ the `-e` option into the command line utility.
 isort provides configuration options to change almost every aspect of how
 imports are organized, ordered, or grouped together in sections.
 
-[Click here](../docs/configuration/custom_sections_and_ordering.md) for an overview of all these options.
+[Click here](docs/configuration/custom_sections_and_ordering.md) for an overview of all these options.
 
 ## Skip processing of imports (outside of configuration)
 
@@ -241,7 +241,7 @@ import a
 
 isort can be ran or configured to add / remove imports automatically.
 
-[See a complete guide here.](../docs/configuration/add_or_remove_imports.md)
+[See a complete guide here.](docs/configuration/add_or_remove_imports.md)
 
 ## Using isort to verify code
 
@@ -272,7 +272,7 @@ project.
 isort provides a hook function that can be integrated into your Git
 pre-commit script to check Python code before committing.
 
-[More info here.](../docs/configuration/git_hook.md)
+[More info here.](docs/configuration/git_hook.md)
 
 ## Spread the word
 

docs/changelog.rst

@@ -1,5 +1,5 @@
 Changelog
 =========
 
-.. include:: ../CHANGELOG.md
+.. include:: generated/CHANGELOG.md
     :parser: myst_parser.sphinx_

docs/conf.py

@@ -1,5 +1,9 @@
 import os
+import re
 import sys
+from pathlib import Path
+
+from sphinx.application import Sphinx
 
 sys.path.insert(0, os.path.abspath(".."))
 
@@ -35,3 +39,21 @@
     "repo_name": "isort",
     "palette": {"primary": "deep-orange", "accent": "deep-orange"},
 }
+
+
+def _generate_includes(app: Sphinx) -> None:
+    """Create Sphinx-friendly copies of some files at build time."""
+    # Use absolute paths based on this file's location
+    root_dir = Path(__file__).parent.absolute().parent
+    gen_dir = Path(__file__).parent.absolute() / "generated"
+    gen_dir.mkdir(parents=True, exist_ok=True)
+
+    for file in ("CHANGELOG.md", "README.md"):
+        content = (root_dir / file).read_text(encoding="utf-8")
+        content = re.sub(r"\]\(docs/(.*?)\.md\)", r"](../\1)", content)
+        (gen_dir / file).write_text(content, encoding="utf-8")
+
+
+def setup(app: Sphinx) -> None:
+    """Register build hooks."""
+    app.connect("builder-inited", _generate_includes)

docs/index.rst

@@ -1,7 +1,7 @@
 Home
 =====
 
-.. include:: ../README.md
+.. include:: generated/README.md
     :parser: myst_parser.sphinx_
 
 .. toctree::