Readthedocs / Sphinx not rendering bullet list from rst file

user_6794815 0
Viewed 3495

I have a set of rst files that I am building in readthedocs with sphinx. The files have multiple bullet lists, but they are not being rendered correctly.

The text appears, but there are no bullet symbols or nesting / indentation.

To make sure it was not my files, I did a direct copy-paste from the sphinx_rtd_theme page (https://github.com/readthedocs/sphinx_rtd_theme/blob/b07560bf97dad3a4266f6145bd4b662ac708ab00/docs/demo/lists_tables.rst)

This is what the rst is supposed to render as (with ::marker for each list item in the html file)

enter image description here

This is what I am getting when I build the same rst using my local sphinx / rtd setup

enter image description here

Is there something I need to fix in my conf.py or other files?

read-the-docs restructuredtext python-sphinx
7 Answers

We had the same issue (bullet points disappearing in lists) after refreshing the conda environment we use for releasing one of our packages. The other solutions listed here (thus far) didn't work for me, but downgrading docutils <0.17 did.

We are using nbsphinx (some of our docs illustrate operations with notebooks), and had recently some issues due to related package versions (jinja2, sphinx, docutils). Based on issues/comments (such as this one and that one), we used various older versions of these packages.

But as of this writing and thanks to the hard work of all the maintainers, we were able to remove all pins except for docutils. FWIW, for our current needs, the relevant subset of packages we use is:

docutils                  0.16                     py38_1  
jinja2                    3.0.0              pyhd3eb1b0_0  
nbsphinx                  0.8.6              pyhd8ed1ab_1    conda-forge
sphinx                    4.0.1              pyhd3eb1b0_0  
sphinx_rtd_theme          0.4.3                      py_0
user_7581740

I had the same issue when using Read-The-Docs as a theme along with Sphinx-AutoAPI. Based on the answer of "Pierre D" I downgraded the docutils using:

conda install docutils=0.16

The solution worked for me. Both, missing bullets and the elongated line spacings were resolved. I guess the problem is caused by a bug in the docutils package and hope it will be fixed soon.

user_20836520
user_19231260

I had the same problem, when listing using *, in the .rst file like:

* first item
* second item

I found out that the problem, in my case, was that I was using the theme sphinx_rtd_theme, but I didn't add it in extensions in the conf.py file. So adding the following worked for me:

extensions = [sphinx_rtd_theme,
# other extensions
]
user_162268850

Other answers here point to docutils as the having the bug. But, the bug is actually in sphinx-rtd-theme. So, even though downgrading docutils seems to work, the solution that worked for us, that I think is better, is to upgrade sphinx and sphinx-rtd-theme past the bugfix. For us, that looked like requiring sphinx>=4.3.0 and sphinx-rtd-theme>=0.5.1 (see our PR)

user_51568870

Creating a new sphinx project solved the problem

user_67948150

Had the same problem:

Creating new sphinx-quickstart didn't work.
Reducing docutils to 0.16 and adding 'sphinx_rtd_theme' to the extensions list in conf.py worked:

extensions = ['sphinx_rtd_theme']
user_129189770
Related