gh links?

[buhtz]

babel/CHANGES.rst

Line 15 in 56c63ca

* Core: Add `babel.core.get_cldr_version()` by @akx in :gh:`1242`

Hello

what are these "gh" things in the markdown code? Microsoft GitHub does not render them correct. No valid link behind it. How to use it?

Regards,
Christian

[akx]

That's not a Markdown file to begin with 😄, it's reStructuredText (.rst), that's used by Sphinx, the thing that runs the documentation site.

The syntax is processed by way of the documentation configuration here

babel/docs/conf.py

Line 259 in 56c63ca

'gh': ('https://github.com/python-babel/babel/issues/%s', '#%s'),

and just so, the links show up as intended here.

[buhtz]

Thank you for the reply. I would say it is not obvious that these are Sphinx-handled links. So readers do need implicit knowledge to understand what is going on.

As a simple solution I would suggest to add a link-to-your-sphinx-generated-docu at the top of that file.

Not so simple: CHANGES.rst is IMHO an end user file. But your CHANGES.st is more template intended to be processed further by another machine (sphinx) before a human being can read it.
Why not move that template somehwere else. Add a "real" CHANGES.rst with the redirecting link to the human-readable-changelog (the spinx generated docu).

[Secrus]

The user-facing changelog is here. The file in the repo is for the developer's needs.

As a simple solution I would suggest to add a link-to-your-sphinx-generated-docu at the top of that file.

That wouldn't work because the file from the repo is included and processed in the documentation, so you would get user-facing documentation starting with a link to itself. Not confusing at all, right?