search

cookiecutter / cookiecutter-django

Cookiecutter Django is a framework for jumpstarting production-ready Django projects quickly.
https://cookiecutter-django.readthedocs.io
BSD 3-Clause "New" or "Revised" License
12.03k stars 2.88k forks source link

Pycharm doesn't support images in reStructuredText #2605

Open ramast opened 4 years ago

ramast commented 4 years ago

Description

Newly generated project contains the file docs/pycharm/configurations.rst which contains embeded images. Pycharm's reStructuredText plugin doesn't support embedding images (at the moment). Using Markdown instead would solve the problem.

Rationale

Providing document specifically for pycharm that pycharm can't properly display might confuse new comers.

Andrew-Chen-Wang commented 4 years ago

Is there an RST plugin for Jetbrains' IDEs? This is what I found online for pycharm: https://www.jetbrains.com/help/pycharm/restructured-text.html

I used to use Pycharm, and it indeed didn't work, but I don't think switching to MD is the solution since many people do like the idea of a more feature rich language. There should be a way to allow for RST if you don't mind investigating. Are you using Docker?

ramast commented 4 years ago

I am not using docker.

Reviews on the plugin page also confirm that images are not supported yet also code for the plugin is not open source. There are no alternative reStructuredText plugins for pycharm that I am aware of.

Another alternative would be auto generating html docs from the reStructuredText ?

ramast commented 4 years ago

I found that pycharm's reStructuredText could load images if it comes from a URL. (i,e http://..... ). Just throwing it there in case it's helpful

browniebroke commented 4 years ago

This file is meant to be included in the documentation generated by Sphinx, not read directly in Pycharm. IMO It's a Pycharm issue, not something with cookiecutter-django...

Yes, we could switch to markdown, but some Sphinx things are rst only. I've played with MyST recently, and it's really good, although it uses a new, unconventional, markdown flavor. The main thing not well supported yet is autodoc.