Sphinx: use doc/ref directives for relative links

[ryan-lane]

This change adds an option (m2r_parse_relative_links) that'll configure m2r to parse internal links into doc or ref directives. It uses urlparse to determine if a link is internal or not based on whether a scheme is detected. A ref is used if only an anchor is provided, otherwise the change assumes a doc is being linked to.

Change for issue #15.

[coveralls]

Coverage decreased (-0.006%) to 40.185% when pulling 0f3527b on lyft:ref-links into 9e0e563 on miyakogi:master.

[codecov-io]

Codecov Report

Merging #16 into master will decrease coverage by 0.04%.
The diff coverage is 95.65%.

@@           Coverage Diff           @@
##           master   #16      +/-   ##
=======================================
- Coverage   96.04%   96%   -0.05%     
=======================================
  Files           3     3              
  Lines         683   726      +43     
=======================================
+ Hits          656   697      +41     
- Misses         27    29       +2

Impacted Files	Coverage Δ
tests/test_renderer.py	99.07% <100%> (+0.05%)	⬆️
m2r.py	93.04% <92.59%> (-0.12%)	⬇️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 83b09b4...5c41773. Read the comment docs.

[coveralls]

Coverage decreased (-0.003%) to 40.187% when pulling 765b2df on lyft:ref-links into 9e0e563 on miyakogi:master.

[coveralls]

Coverage decreased (-0.003%) to 40.187% when pulling 1832a88 on lyft:ref-links into 9e0e563 on miyakogi:master.

[coveralls]

Coverage increased (+0.1%) to 40.318% when pulling 1aa9d31 on lyft:ref-links into 9e0e563 on miyakogi:master.

[coveralls]

Coverage increased (+0.1%) to 40.315% when pulling 1aa9d31 on lyft:ref-links into 9e0e563 on miyakogi:master.

[ryan-lane]

Based on the way the tests run, I don't think it's going to be possible for me to hit the coverage required. The diff lines that aren't being covered are either 2/3 compat, or are when m2r is called outside of sphinx, which isn't being tested.

[lorengordon]

Just ran into this problem, would be great to see this merged!

[lorengordon]

@ryan-lane Quick question... was testing this branch and the anchor links do not appear to be working correctly. Well, they may be rendered to an rst ref as coded, but sphinx is having none of it.

[foo](#foo)

# foo

The doc above generates a warning in sphinx:

WARNING: undefined label: foo (if the link has no caption the label must precede a section header)

The released version of m2r works fine with this kind of anchor link, so I think this would be a regression. Unless I'm doing something wrong, which is ultimately my "quick question". 😄 Is there a "correct" way to write the markdown such that sphinx will render the ref link properly?

[ryan-lane]

@lorengordon hm. that should work. I'll need to take a look.

[ryan-lane]

@lorengordon hm. that should work, but I've reproduced your issue. I'll fix that and push it in.

[mrexodia]

What is required for this pull request to get merged? I would like to use this feature to get rid of recommonmark in my sphinx project...

[miyakogi]

I'm sorry for late response.
I merged this PR.
Thank you for your great efforts!

[ryan-lane]

Awesome. Thanks for the merge!