[good-first-issue] Expose the change log via Sphinx docs

[webknjaz]

I was browsing https://mypy.rtfd.io and was trying to find the change log, the search didn't find anything useful and I ended up locating it in the repository @ https://github.com/python/mypy/blob/master/CHANGELOG.md. But it was rather frustrating.

It is usually possible to show the same change log document in Sphinx. The challenge here is that it's in Markdown and Sphinx isn't set up to stomach it.

The solution is integrating MyST-parser by adding it to https://github.com/python/mypy/blob/fe15ee6/docs/requirements-docs.txt and https://github.com/python/mypy/blob/fe15ee6/docs/source/conf.py#L38, followed by creating a changelog.md inside https://github.com/python/mypy/tree/fe15ee6/docs/source/ containing something like https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-a-file-from-outside-the-docs-folder-like-readme-md. Though, it can be changelog.rst too (https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-markdown-files-into-an-rst-file).
Finally, a changelog entry needs to be added to ToC around https://github.com/python/mypy/blob/fe15ee6/docs/source/index.rst?plain=1#L99C4-L105C7.

P.S. While writing this, I realized that https://mypy-lang.org does not have a change log link either. I don't know where its source is but it'd be nice to link the Sphinx-exposed change log page from that too.

[quinn-sasha]

I will try to solve this.

[quinn-sasha]

followed by creating a changelog.md inside https://github.com/python/mypy/tree/fe15ee6/docs/source/ containing something like https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-a-file-from-outside-the-docs-folder-like-readme-md. Though, it can be changelog.rst too (https://myst-parser.readthedocs.io/en/latest/faq/index.html#include-markdown-files-into-an-rst-file).

Can I ask you a question about this part?

I think you suggested two ways to include mypy/changelog.md into mypy/docs/source/....
To use markdown file or rst file.

Question: Which is better for this project, markdown or rst.

The below is my comparison of markdown and rst.

	changelog.md	changelog.rst
pros	Do not need docutils>=0.17 which is not listed in docs/requirements-docs.txt.	Consistency with other rst files.
cons	While other files are mainly rST file, only changelog.md will be markdown.	To nclude Markdown files into an rST file, we need parser docutils>=0.17 for parser option.

[webknjaz]

Question: Which is better for this project, markdown or rst.

The trampoline file under docs/ would be just a few lines, so it shouldn't really matter in my opinion. Not sure what the maintainers think.

we need parser docutils>=0.17 for parser option.

I don't think it's a problem. The docs are usually built in one environment, with no need to support multiple variants of transitive deps.

[quinn-sasha]

The trampoline file under docs/ would be just a few lines, so it shouldn't really matter in my opinion.

Then, I will go for changelog.md.

Thank you for your help.

[quinn-sasha]

P.S. While writing this, I realized that https://mypy-lang.org does not have a change log link either. I don't know where its source is but it'd be nice to link the Sphinx-exposed change log page from that too.

I don't think this feature is very important.
It is because if someone visit this link, the releases occupy the main page.

[webknjaz]

Fair