Closed mforbes closed 3 years ago
The command-line interface for this project only supports reStructuredText. If you want to render markdown, you'll need to use the Python API instead.
Makes sense. Thanks.
Might I recommend a comment to this effect on the front-page where it says that Markdown is supported? It would also be really nice if perhaps all supported formats could be properly processed from the command line. I am trying to find a workflow where I can see what my README file will look like on PYPI before uploading it have then having to bump my version because I made some documentation errors.
Is there another official way to do this? twine check
is kind of a pain because it requires you to build the distribution first, and does not let you see the resulting documentation.
Am I right that this is the code that actually generates the documentation on PYPI or should I be looking somewhere else?
Might I recommend a comment to this effect on the front-page where it says that Markdown is supported? It would also be really nice if perhaps all supported formats could be properly processed from the command line. I am trying to find a workflow where I can see what my README file will look like on PYPI before uploading it have then having to bump my version because I made some documentation errors.
I'm proposing to just remove it in #197. Unfortunately this project isn't really intended to be a command-line tool -- at least, we don't really have the capacity to support that use case we'll right now.
Is there another official way to do this? twine check is kind of a pain because it requires you to build the distribution first, and does not let you see the resulting documentation.
There are lots of tools for rendering markdown if that's the goal. We don't really do anything too much different, except that they won't do the same HTML sanitization we do here.
You also could write a short Python script to call this projects importable Python API directly, that's what I'd probably recommend.
Am I right that this is the code that actually generates the documentation on PYPI or should I be looking somewhere else?
You are correct! Which is why the command-line use case is not well supported here, because PyPI doesn't use it.
That makes sense, but it is really a pain for users that there is no official way to see how their documentation will be rendered without trying to upload it. A simple dispatch based on file type would keep this rather useful functionality.
# __main__.py
from __future__ import absolute_import, print_function
import argparse
import readme_renderer.rst, readme_renderer.markdown
import sys
if __name__ == "__main__":
parser = argparse.ArgumentParser(
description="Renders a .rst or .md README to HTML",
)
parser.add_argument("input", help="Input README file", type=argparse.FileType("r"))
parser.add_argument(
"-o",
"--output",
help="Output file (default: stdout)",
type=argparse.FileType("w"),
default="-",
)
args = parser.parse_args()
if args.input.name.split(".")[-1].lower() == "md":
render = readme_renderer.markdown.render
elif args.input.name.input.split(".")[-1].lower() in {"rst", "rest"}:
render = readme_renderer.rst.render
else:
raise NotImplementedError("Unknown input format {}".format(args.input))
rendered = render(args.input.read(), stream=sys.stderr)
if rendered is None:
sys.exit(1)
print(rendered, file=args.output)
I'm not planning on removing the functionality, just the docs about it. You're welcome to submit a PR to improve the CLI though!
@di Done.
The following fenced code in a markdown file
tst.md
gives an error(WARNING/2) Inline literal start-string without end-string.
tst.md
: