search

pythonarcade / arcade

Easy to use Python library for creating 2D arcade games.
http://arcade.academy
Other
1.68k stars 320 forks source link

CONTRIBUTING.rst has broken links when viewed on GitHub #1910

Closed pushfoo closed 5 months ago

pushfoo commented 11 months ago

Bug Report

tl;dr :ref:s and other directives don't seem to render in a GitHub view of an .rst file, even for targets within the same file

System Info

Version 117.0.5938.62 (Official Build) built on Debian 11.7, running on Debian 11.6 (64-bit)

Actual behavior:

The Testing link in After making changes does not link anywhere and does not render correctly: image

Expected behavior:

The Testing link in After making changes:

  1. Works when clicked
  2. (Ideally) renders cleanly

Steps to reproduce/example code:

  1. Go to After making changes
  2. Observe the link
  3. Attempt to click it

Correcting the capitalization does not change this either. It appears GitHub cannot render :ref: targets.

Root causes

There seems to be limited post-processing of directives in GitHub views

Implications

This may block #1302 and affect #1886, both of which I was looking at when I noticed this.

Possible ways to fix it

  1. Use a script which renders CONTRIBUTING.rst as markdown
  2. Go back to old approach: the abbreviated model + links to the web site

I'm not in favor of clever scripts because those will probably break at some point.

cspotcode commented 11 months ago

Go back to old approach: the abbreviated model + links to the web site

It can be more than abbreviated, it can be a single link to the website with zero additional information.

pushfoo commented 11 months ago

I'm ok with that option, but might make it more or less a toctree dump for the relevant pages. @pvcraven any objections? I don't see the value of keeping this page seperate then reaching back through the hierarchy to include it.

einarf commented 9 months ago

Can't we just change README and CONTRIBUTING into markdown files? They don't really need the complexity rst has to offer in the first place.

Cleptomania commented 9 months ago

Actually the CONTRIBUTING file is included directly in the doc build, though it would be trivial to add in MyST Parser extension to sphinx to allow us to just include the Markdown(and maybe use more markdown in the future?)

einarf commented 7 months ago

Why don't we just link to the file instead and make it markdown? That has such a lower complecity. It makes sese that the contribution guidelines are part of the code anyway and not the docs. This is pretty standard in other projects.

pushfoo commented 5 months ago

This seems done. We switched to markdown for the current file.