Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: Make change-log visible in mypy documentation #17742

Merged
merged 10 commits into from
Sep 15, 2024
Merged
1 change: 1 addition & 0 deletions docs/requirements-docs.txt
Original file line number Diff line number Diff line change
@@ -1,2 +1,3 @@
sphinx>=5.1.0
furo>=2022.3.4
myst-parser>=4.0.0
3 changes: 3 additions & 0 deletions docs/source/changelog.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
<!-- This file includes mypy/CHANGELOG.md into mypy documentation -->
```{include} ../../CHANGELOG.md
```
5 changes: 4 additions & 1 deletion docs/source/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,10 @@
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ["sphinx.ext.intersphinx", "docs.source.html_builder"]
extensions = ["sphinx.ext.intersphinx", "docs.source.html_builder", "myst_parser"]

# To prevent myst-parser from warning header level increases
suppress_warnings = ["myst.header"]

Choose a reason for hiding this comment

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

Don't do this. Instead, decrease the indentation in CHANGELOG.md. Look at https://github.com/python/mypy/blob/72c413d/CHANGELOG.md?plain=1#L14 — it uses #### (H4) right after ## (H2). So MyST-Parser is correct to flag this. It's a real problem that needs to be fixed rather than ignored.

Choose a reason for hiding this comment

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

Looks like it should be auto-replaced across that entire file. Running sed -i 's/^####/###/g' CHANGELOG.md should do what's needed to correct the mistake.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

Thank you very much for your guide!


# Add any paths that contain templates here, relative to this directory.
templates_path = ["_templates"]
Expand Down
1 change: 1 addition & 0 deletions docs/source/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -103,6 +103,7 @@ Contents
error_code_list2
additional_features
faq
changelog

.. toctree::
:hidden:
Expand Down