search

pypa / readme_renderer

Safely render long_description/README files in Warehouse
Apache License 2.0
158 stars 89 forks source link

Add `render_readme` command to render HTML locally. #101

Closed khorn closed 6 years ago

khorn commented 6 years ago

This allows users to render HTML locally in order to preview the rendered markup prior to uploading a package. Optionally, the user can also control syntax highlighting and send the markup to a web browser.

khorn commented 6 years ago

FYI, replaces #53

theacodes commented 6 years ago

@khorn it's a good start, but there seems to still be some todos. Will you ping me when you're ready for me to review (or if you get stuck?)

khorn commented 6 years ago

@theacodes Ping.

theacodes commented 6 years ago

Hi @khorn, I don't think it's very useful to have console output for this. I would prefer us just to do the HTML preview.

hsiaoyi0504 commented 6 years ago

Is there any update of this ? I agree that having console output for this doesn't quite useful, but it would be good to have a output html generated for more easier sharing.

theacodes commented 6 years ago

@hsiaoyi0504 it's up to @khorn if they want to update their PR. You're also welcome to start a new PR based on this one to address review comments.

khorn commented 6 years ago

@theacodes Sorry it's been so long...

I'm a bit confused by your comment. If the intention was to only do an HTML preview in a web browser, then I don't understand why #53 wasn't accepted. It does exactly that and works (or at least worked...it appears to have developed some conflicts) perfectly well.

The intent of this change was to (a) replace/update that branch, and (b) also address the request in #52, which asks for a command to generate an HTML preview in a file.

This was exactly what I was asked to do at the PyCon sprint. The only difference is I decided to send the generated HTML to stdout, rather than a file, as that seemed more flexible.

I figured that sending the results to stdout would allow the command to be sent to linters, spell checkers, etc. perhaps as part of a release checklist or CI/CD workflow.

Personally, it seems to me that stdout output is far more useful than a webbrowser preview. I would certainly rather have a tool that sent HTML to stdout, which I could then pipe anywhere, rather one that only allowed me to preview the HTML in a browser.

Why do you disagree?

theacodes commented 6 years ago

@khorn sorry for the confusion.

I think it's surprising behavior for an interactive command-line tool to output non-human-readable code. I'd prefer if we had the following behavior, let me know what you think:

  1. Running render-readme with no arguments produces a readme.html file in the current directory.
  2. Running render-readme --output - outputs to stdout. (this behavior is consistent with argparse

For (2) don't bother doing console color highlighting, as the use case for outputting the raw html to stdout is to pipe to other programs which likely won't be fans of any escape sequences.

khorn commented 6 years ago

@theacodes I'm fine with your suggestions, just haven't gotten to it yet. I do still intend to!

theacodes commented 6 years ago

Cool! No worries. :)

On Thu, Sep 27, 2018, 3:02 PM Kevin Horn notifications@github.com wrote:

@theacodes https://github.com/theacodes I'm fine with your suggestions, just haven't gotten to it yet. I do still intend to!

— You are receiving this because you were mentioned.

Reply to this email directly, view it on GitHub https://github.com/pypa/readme_renderer/pull/101#issuecomment-425257294, or mute the thread https://github.com/notifications/unsubscribe-auth/AAPUc-l_suRp1P640uVEm19uSE3R0bWpks5ufUrygaJpZM4T-m0S .