search

scikit-tda / kepler-mapper

Kepler Mapper: A flexible Python implementation of the Mapper algorithm.
https://kepler-mapper.scikit-tda.org
MIT License
623 stars 180 forks source link

idea: rewrite main readme and release file to .rst, import into docs #221

Open deargle opened 3 years ago

deargle commented 3 years ago

We can use sphinx to DRY use the repo's README as the index page for the docs., if we rewrite the readme to be .rst instead of .md. Same for RELEASE.txt -- we can have it rendered as a docs page. I'll open a PR with the same as part of getting ready for 2.0.0 unless you're opposed.

sauln commented 3 years ago

Sounds great!

deargle commented 3 years ago

I'm not sure this is a good idea anymore. On the github readme, we want to have a link to the documentation. But if we use the github readme as the documentation index page, then that means the documentation has a link to itself at the top, potentially making people think they're not already looking at the documentation.

I did do a small DRY where I'm just linking to the doc's "how to cite" section instead of repeating the how-to-cite info in the github readme.

sauln commented 3 years ago

We do have the link to the link to the documentation in the about section in the righthand pane on github. You think that would be sufficient enough to remove the reference in the readme?

deargle commented 3 years ago

I missed that. Yes, I think that would be sufficient.

Are you okay with adding a new dependency to the docs build? m2r2 would permit us to import a markdown README.md into sphinx (it converts it to rst).

sauln commented 3 years ago

Sure! dependencies for docs are easy since to users have to concern themselves with it.