diff --git a/.gitignore b/.gitignore index 5530b0cd..fd352dfb 100644 --- a/.gitignore +++ b/.gitignore @@ -78,3 +78,4 @@ pyvenv.cfg # Sphinx documentation build docs/_build/ +docs/generated/ diff --git a/CHANGELOG.md b/CHANGELOG.md index d3fa9f77..4d0ad2a7 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/README.md b/README.md index d20e2159..522b27d3 100644 --- a/README.md +++ b/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 diff --git a/docs/changelog.rst b/docs/changelog.rst index 3b4ed43b..b36b03f6 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -1,5 +1,5 @@ Changelog ========= -.. include:: ../CHANGELOG.md +.. include:: generated/CHANGELOG.md :parser: myst_parser.sphinx_ diff --git a/docs/conf.py b/docs/conf.py index d23f8d72..a9873424 100644 --- a/docs/conf.py +++ b/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) diff --git a/docs/index.rst b/docs/index.rst index 3178c600..973cdb3f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,7 +1,7 @@ Home ===== -.. include:: ../README.md +.. include:: generated/README.md :parser: myst_parser.sphinx_ .. toctree::