uranusjr commented on pull request #19124: URL: https://github.com/apache/airflow/pull/19124#issuecomment-950616687
So there are, strictly speaking, three variants of link references you can do in restructuredText: 1. Named call-out (single underscore suffix and a `.. _name` directive somewhere else) 2. Named fold-in (i.e. embedded) 3. _Unnamed_ fold-in (suffixing with two underscores instead of one) Using the call-out form is generally preferred since it makes the restructuredText easier to read in its pure text form, and is also the most flexible when rendering (although it's mostly irrelevant for HTML). It also makes referencing a term multiple times in a document trivial (just add an underscore suffix each time the term appears). The second most useful form is the _unnamed_ fold-in since sometimes you don't want the hyperlink to have a name. This is useful for cases like Line 201 in `CONTRIBUTING.rst`; naming the hyperlink `here` is close to useless (and will actually generate an error if you add another `here` that links to somewhere else in the same document), so it's best to write it like this instead (notice the extra underscore at the end) ```rst between the two are explained `here <https://github.com/apache/airflow/blob/main/CONTRIBUTING.rst#development-environments>`__. ``` Personally I think the named fold-in is the least useful, but it's sometimes convenient when you want to keep the link as close to the text as possible, I guess. -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
