Python code blocks not rendering with readthedocs and sphinx

Question

I'm building docs for a python project using Sphinx and readthedocs. For some reason, the code blocks aren't rendering after building the docs, and inline code (marked with backticks) appears italic. I've checked the raw build, there was a warning that the exomagpy module couldn't be found which I resolved by changing ".." to "../" in the os.path.abspath() part of conf.py, this didn't appear to change anything in the docs. There was a similar question here on stackoverflow, I tried the solution but it didn't change.

The raw build can be found here: https://readthedocs.org/api/v2/build/17574729.txt

The docs are being built from the "Develop" branch of the github page (link below)

Here is the link to the github page: https://github.com/quasoph/exomagpy/tree/Develop

The repo is structured like so:

>.vscode
>build/lib/exomagpy

>docs
   >conf.py
   >rst files (.rst)
   >makefile
   >make.bat

>exomagpy.egg-info

>exomagpy
   >__init__.py
   >module files (.py)

>.readthedocs.yml
>requirements.txt
>setup.py

Here are my files:

conf.py

import os
import sys
sys.path.insert(0, os.path.abspath("../"))

# project info

project = "exomagpy"
root_doc = "index"
release = "1.3.0"

# general config

extensions = ["sphinx.ext.autodoc","sphinx.ext.napoleon","sphinx.ext.autosummary"
]

templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# html options

html_theme = 'sphinx_rtd_theme'
html_static_path = []

.readthedocs.yml

version: 1

build:
  os: ubuntu-20.04
  tools:
    python: "3.8"
  
sphinx:
  configuration: docs/conf.py

python:
  version: 3.8
  install:
    - method: setuptools
      path: .
    - requirements: requirements.txt

dependencies:
  - python=3.8

requirements.txt

numpy
matplotlib
pandas
tensorflow
lightkurve
requests
sphinx==5.1.1
sphinx_rtd_theme==1.0.0

setup.py

from setuptools import setup, find_packages

setup(
    name = "exomagpy",
    version = "1.3.0",
    author = "Sophie",
    author_email = "email",
    url = "link",
    description = "description",
    packages = find_packages()
)

Any help really appreciated, please let me know if more information is needed.

You need to add a blank line between `.. code-block:: python` and the content of the block. https://raw.githubusercontent.com/quasoph/exomagpy/main/docs/tutorials.rst — mzjn, Jul 30 '22 at 05:39
@mzjn thank you for the reply, I've tried that and nothing changed (edited the post to say I'm building the docs from the "develop" branch where there's a blank line, not "main") — Sophie Frankel, Jul 30 '22 at 10:51
Here it looks fine: https://exomagpy.readthedocs.io/en/latest/tutorials.html — mzjn, Jul 30 '22 at 11:15
@mzjn hm, maybe it was an issue with my device/readthedocs not updating. Thank you — Sophie Frankel, Jul 30 '22 at 12:17

score 3 · Accepted Answer · answered Jul 30 '22 at 07:59

As @mzjn pointed out, a blank line is required between the code-block directive and the code that is supposed to be highlighted.

https://raw.githubusercontent.com/quasoph/exomagpy/main/docs/tutorials.rst

.. code-block:: python

    import exomagpy.predictExo
    exomagpy.predictExo.tess()
    exomagpy.predictExo.kepler()

Additionally for inline code literals, single backticks in reStructuredText are rendered as italics, as you realized, whereas in Markdown and its flavors it would render as an inline code literal. For reStructuredText, surround the literal with double backticks:

``inline_literal``

Thanks for your reply, I should've specified in the post that I'm building off the "develop" branch where there is a space between the directive and the code. I've tried changing to double backticks and nothing has changed, none of the code is rendering. Will edit the post now. — Sophie Frankel, Jul 30 '22 at 10:45

Python code blocks not rendering with readthedocs and sphinx

1 Answers1