Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

remove M2R as dep #527

Closed
lwasser opened this issue Apr 8, 2020 · 8 comments
Closed

remove M2R as dep #527

lwasser opened this issue Apr 8, 2020 · 8 comments
Assignees

Comments

@lwasser
Copy link

lwasser commented Apr 8, 2020

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.

  1. convert all files to .rst format (changlog and maybe the readme)
  2. link to files on github in md format and NOT print them as include files in the docs like this:
@mbjoseph
Copy link
Member

mbjoseph commented Apr 8, 2020

@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

@lwasser
Copy link
Author

lwasser commented Apr 8, 2020

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?

@mbjoseph
Copy link
Member

mbjoseph commented Apr 9, 2020

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
Copy link
Member

mbjoseph commented Apr 9, 2020

Does linking to the files on GitHub sound like a good way forward @lwasser?

@lwasser
Copy link
Author

lwasser commented Apr 9, 2020

@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

@lwasser
Copy link
Author

lwasser commented Apr 24, 2020

@nkorinek didn't you implement this? i just can't find the PR to close it :)

@lwasser
Copy link
Author

lwasser commented Apr 27, 2020

ok it's definitely not been implemented as pr's are failing. @nkorinek let's deprecate m2r in this project as well!!

@lwasser
Copy link
Author

lwasser commented May 1, 2020

fixed via #535 thank you @nkorinek !!!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants