remove M2R as dep
lwasser opened this issue · 8 comments
M2r converts markdown to rst. however it's currently unmaintained and there is a bug related to the new version of sphinx. we only use it to convert our changelog to print in the docs. One quick fix would be to simply link to the changelog in the release notes rst file. We could then completely drop m2r. an alternative is to convert the changelog to .rst and the readme which could work but would take a bit more time.
regardless we should not depend upon m2r anymore given there is a fix but it's unmaintained so it's just not worth using. i'm looking for input from @mbjoseph and @nkorinek on which direction we should go.
- convert all files to .rst format (changlog and maybe the readme)
- link to files on github in md format and NOT print them as include files in the docs like this:
@lwasser it's been a while since I've done much with sphnix, but is there a third option to use recommonmark with Sphinx? https://www.sphinx-doc.org/en/master/usage/markdown.html
hey @mbjoseph yes matthew had mentioned this here: sphinx-doc/sphinx#7420 (comment) he just seemed to think it was not a complete solution but i saw this without actually trying anything. they are moving towards .rst readmes and such but i'm really open to that extension if it serves our needs. i guess we would need to just try it out?
Ok I futzed around with this a bit this morning. It doesn't seem like recommonmark is going to be a simple solution.
Of the two options you laid out, I think option 2 (linking to the files on GitHub) seems like the simplest approach.
@mbjoseph i'm fine with just linking to files. thank you so much for playing with this. i just haven't had time. we could d this on all of our packages too and just forgo includes for .md files