search

crate / crate-docs

Common build system, QA tools, style guides, and other meta miscellanies for doing docs at Crate.io.
Apache License 2.0
2 stars 1 forks source link

Add a `preview-rst` helper for working with RST files #74

Closed nomicode closed 3 years ago

nomicode commented 3 years ago

This change does the following:

additional commentary follows

I developed the preview-rst script to help me with my editing workflow. the bulk of the work was done in my personal time, but I am hereby licensing it in full to Crate.io

the impetus for creating this PR today came from my work on https://github.com/crate/crate-docs/pull/72. I noticed a bunch of errors with the CHANGES.rst file, and I was relying on my homegrown preview-rst file to help me review my changes as I worked to fix them

I became frustrated with the no-CSS output that pandoc generates, so I promised myself I would come back to this in the evening and try to figure out how to improve on what I had. the result was as you see here: basically, the script creates a tiny Sphinx project and uses sphinx-autobuild to provide live reloading

this was such a big improvement, I decided that it was a good idea to clean up the code and share it with other people. I also decided that this repository is the most logical place for it to live

this script is a work in progress and is littered with TODO markers in the comments. over time, I hope to be able to improve this. but for now, it works

I actually have a wrapper script written for BBEdit that already integrates this script with my editor, so I can just press \<Command-P> to get a preview. it's proven itself incredibly helpful over the past couple of weeks. so I am hoping that by sharing this, others can reap the benefits too

in time, I plan to contribute my wrapper script, and possibly the lint-rst script I have been using. this is very much a mini passion project for me though, and I am mostly squeezing it in between the cracks, so please don't expect to see very frequent updates

to give you an idea of what this does, here's a screenshot of the preview that is generated when you run this script on CHANGES.rst (my original use-case):

image

nomicode commented 3 years ago

a little present for you, @amotl 😎

amotl commented 3 years ago

Très chic! Merci beaucoup.

Just a small question to make up an appropriate slot in my mind: This is essentially an advanced version of rst2html.py, which not only previews plain reStructuredText, but actually Sphinx-flavored reStructuredText, right?

nomicode commented 3 years ago

@amotl I replied to all your comments and pushed fixups. can you take a look? some of my comments request that you create issues

I also added two more bonus commits :)