[OH-Dev] Problem with using Sphinx's :doc: syntax

[Asheesh Laroia]

Hi Eeshan!

It's usually best if you ask on the mailing list, as Carol Willing (who is
on the list) is especially active in docs stuff in OpenHatch-land. So I've
taken the liberty of sending this to the list.

But I would say... yeah, if GitHub doesn't render the cool Sphinx syntax,
we shouldn't use it in the CONTRIBUTING.md.

If we can convert CONTRIBUTING.md to be a rST file, that's probably good
just for consistency. But we should probably leave a comment (see
http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments )
indicating that we only use the limited rST syntax subset that GitHub
supports.


On Sun, Jun 8, 2014 at 10:22 AM, Eeshan Garg <jerryguitarist at gmail.com>
wrote:

> Hello!
>
> I worked on the issue about the broken link to the Contributor Guide in
> CONTRIBUTING.md and after merging my pull request about that issue, you
> commented on my commit and advised me to adjust the file to use Sphinx's
> :doc: syntax to link to the Contributor Guide instead of an HTTP link. I
> got stuck while working on it but after asking for advice on IRC, I was
> able to do it. I changed CONTRIBUTING.md to CONTRIBUTING.rst and also put a
> copy of the new .rst file in the docs directory so that they can be
> rendered by render_docs.py. I tested my changes and they worked.
>
> But after doing all of that, I realized that if you open a .rst file on
> GitHub, it is parsed as Markdown and not as reStructuredText. So something
> like:
>
> :doc: `some text </directory/file>`
>
> is displayed on GitHub as raw code, as the Markdown parser does not
> recognize it as a link at all. So if you go to the docs directory on GitHub
> and try to click on a link written in Sphinx's syntax in one of the .rst
> files, it won't take you anywhere. So wouldn't it be okay if we leave the
> CONTRIBUTING.md file as it is, given that it is not a part of the official
> documentation and should just be a pointer to the docs for people
> interested in contributing.
>
> I would really appreciate it if you could give me some advice on what to
> do next. I very well understand and respect that you're a busy person, so
> my sincere apologies for the length of this mail.
>
> Hope you're well. :)
>
> Thanks & regards,
> Eeshan Garg
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openhatch.org/pipermail/devel/attachments/20140609/0c79a649/attachment.html>