Question about installation for Readthedocs and a related question about using markdown with the Sphinx for a RTD site

Question

Please bear with me as I am a tech writer, not a developer. I actually have two questions, but they are related...

Q1. We want to create a documentation project on GitHub and hosted in ReadTheDocs. If I understand correctly, to generate the documentation, ReadTheDocs uses software installed on the ReadTheDocs server, not on my machine, so strictly speaking I don't need to install anything locally? I could just upload files directly to GitHub and make all the edits there? (As far as I understand, installing python locally is only needed if I want to see a local version of the Documentation website, which is highly desirable, but not essential? I am eventually planning on doing this, but first I would like to understand better what is going on.)

Q2. I am experimenting with hosting our ReadTheDocs documentation using the Sphinx generator. However, I want to work with markdown files, not RST files. As far as I understand, to enable this I need to "install the myst_parser extension". My doubt is if the answer to my previous question happens to be "yes" then doesn't that mean this extension needs to be installed on the ReadTheDocs server? How do I do this?

Thanks

Adrian

Answer 1

It's not possible to add extensions to a Sphinx project without looking at the configuration code for your Sphinx project. As such, you would have to take some steps into development - but perhaps you can enjoy this tutorial for getting started with Sphinx? I think it's made with technical writers in mind, too: https://techwritingmatters.com/documenting-with-sphinx-tutorial-intro-overview

Q1:

I recommend that you follow the above tutorial so you are able to build a Sphinx project locally while you are setting up extensions. Following the tutorial will get you familiar with basic concepts that will make everything easier and less mythical.

Once you have setup your GitHub project and wrestled with the configuration code changes required in Q2, you can enter a workflow where you edit files on GitHub and Read the Docs does the rest.

No local builds required, no command line etc. Just pure writing.

Q2:

You will also need to create a so-called requirements.txt and configure your Read the Docs project to install the Python packages in that file.

You can configure Read the Docs in two ways:

1. Method 1: Via the Dashboard UI, you will find an option for requirements.txt

2. Method 2: By creating a readthedocs.yaml specifying the following:

# .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Build documentation in the docs/ directory with Sphinx
sphinx:
   configuration: docs/conf.py

# Optionally declare the Python requirements required to build your docs
python:
   install:
   - requirements: docs/requirements.txt

You need to add a requirements.txt because myst_parser is distributed as a Python Package and you need to tell Read the Docs how to get it (and which version). Create a file docs/requirements.txt containing the following:

Sphinx>=5,<6
myst_parser>=0.18,<0.19

Notice the version logic here: We are telling Read the Docs that we want Sphinx in the 5.x series and myst_parser in 0.18.x series. This is to avoid sudden build failures in the future.

You are responsible for updating versions of Sphinx and extensions. You can also remove the version pinning, but then your project might fail to build suddenly in case new incompatible releases come out.

Finally, will need to edit your conf.py file in order to add the myst_parser extension. You should find the line containing the extensions variable and change that.

extensions = [
    "myst_parser",
]

You will probably use the above instructions again in the future since there are many good extensions and themes for Sphinx.

Good luck!