Is the CONTRIBUTING.rst guide badly formatted ?

[zonzille]

Hi there,

I have a question regarding the formatting of rst code in the contributing guide in the beets repo.

The problem :

I'm trying to find some rookie stuff to do in order to get familiar with the codebase, but the first thing that struck me while reading the docs was that the :doc: links don't point to the destination they're supposed to. Instead they seem to point to themselves, clicking them makes me stay on the same page but modifies the URL slightly by adding some stuff after a #. Like if it was just pointing to a section in the page I'm already reading.

Example for clarity : clicking :doc:`Code of Conduct <code_of_conduct>` should direct me towards https://github.com/beetbox/beets/blob/master/CODE_OF_CONDUCT.rst
But instead it modifies my URL from https://github.com/beetbox/beets/blob/master/CONTRIBUTING.rst to https://github.com/beetbox/beets/blob/master/CONTRIBUTING.rst#id1

The solutions I tried all failed, and from what I know the formatting seems correct to me !...

So instead of opening an issue and having someone fix that for me, I was thinking maybe someone here could explain me how to fix this, so I get a better understanding of this issue.

Thanks in advance and I hope that's not breaking any guidelines !

[zonzille]

Adding a screenshot just so that the issue is clearer because my depiction of it, I realise, is not that clear.

Bad formatting in the rendered version :

URL before clicking on the :doc: link :

URL after clicking :

URL that should've loaded after clicking :

[semohr]

The contribution guide is primarily designed to be parsed by sphinx and viewed on our documentation website. However, it could be useful to also maintain a plain Markdown version. Might allow us to keep the guide more concise while moving some of the more detailed information into the developer documentation.

I would be happy to review any changes you might come up with to make this more approachable for starters ;)

[zonzille]

Ohhh so that's why ! Sorry that was kind of a 'missed the point' question then ! I had just not come across the interpreted version on the docs website, I tend to read stuff on Github. Unfortunately I know absolutely nothing about markup languages or web coding in general, the only thing I've even remotely studied is Python...

Where would I be headed if I needed to learn a bit about maintaining a markdown version of the guide ?

Oh and thank you for your reply :)

[semohr]

No worries at all, it can definitely feel a bit convoluted at first, especially when you’re just getting into it!

I think learning a bit of reStructuredText (reST) and sphinx is a good skill for any upcoming Python developer, it’s used in most larger projects (including Python’s own docs) to expose documentation online. But you don’t need to be an expert to contribute! Even small edits or clarifications in the guide are already very valuable.

I’m going to mark this as resolved, but don’t hesitate to jump back in with questions or even a small contributions, every little improvement is appreciated!

[zonzille]

Okay thank you very much ! I definitely will, and if you don't see pull requests from me soon don't worry, I'm not the fastest learner but I'll be at it. Thanks again !