rayrrr
commented
2 years ago After thinking this over a bit more, I'm hoping there's a solution that, with minimal added complexity, will allow us to have the best of both worlds. If we can parse the code examples in reStructuredText to unit test them, then in theory, we should also be able to parse the code examples to run them, and then geojson.dumps the output of each, and then programmatically generate a markdown file that visualizes all examples in a way that is guaranteed to stay in sync even if the code snippets change, all as part of the CI process.
This project's README is currently written in reStructuredText format, which provides for additional functionality that is lacking from Markdown. The main additional functionality used in this project is the ability to introspect code snippets and run unit tests on them (to help ensure valid code examples in documentation).
However, the README contains several links to map visualizations which are sadly no longer active and which we are unable to fix for reasons.
The good news is that GitHub has recently announced native support for GeoJSON map visualizations in GitHub Flavored Markdown (GFM). So, this is the shortest path to adding map visualizations back to the README. Here's an example native GeoJSON Point visualization showing the location of the East River Amphitheater Park in NYC.
This new feature is only available for GFM though, not reStructuredText. So, we can have beautiful map visualizations along with each example in the README, or we can introspect and unit test the code snippets for each example in the README, but not both.
Furthermore, from a packaging perspective, GFM has been natively supported by the PyPi renderer just like reStructuredText since 2019, so that is no longer a reason to avoid GFM.
My inclination would be to convert the README to GFM and leverage the map visualization feature, as I feel it would make the documentation more accessible, but I want a sense of community support for this.
If you think sacrificing unit-tested code snippets for built-in GeoJSON map visualizations in the README is a good idea, please give this issue a thumbs up. If you disagree, thumbs down. And of course, comment with any pertinent thoughts.
Thank you!