User Feedback on Tutorial from Write the Docs Writing Day

[JeanSiegel]

New Read the Docs user/ new github user. Absolutely no python experience.

Tutorial Doc
Preparing your project on GitHub
3rd bullet - "Make sure the project is “Public”, rather than “Private”." - not sure where to find this, nor how to check what is set. just continued.

Sign up for Read the Docs
To sign up for a Read the Docs account, navigate to the Sign Up page

Sign up page takes me to "ready to share your docs" -- don't know what to do at this point. I guess I've authorized already. Add to the step - if you already have a readthedocs account, and logged in, do x.

But once past that step, the "Importing the project to Read the Docs" was easy to follow.

My build failed. "Extension error:
Could not import extension sphinx.builders.linkcheck (exception: urllib3 v2.0 only supports OpenSSL 1.1.1+, currently the 'ssl' module is compiled with OpenSSL 1.0.2n 7 Dec 2017. See: urllib3/urllib3#2168)"
After much reading and, I decided to install the the .readthedocs.yaml -- mentioned in "Adding a .readthedocs.yaml file"

In the Configuration file section, I'm not sure what to do. I think I'll click the Edit on GitHub and see what happens. I'm feeling discouraged and ready to quit. --- it's just the docs... where can I copy a config from to my project that won't work without it?

OK, I'm going to copy the text in the Sphinx tab (why not a copy button?) and commit a .readthedocs.yaml file.

Built again. Got the "ERROR: Could not open requirements file: [Errno 2] No such file or directory: 'docs/requirements.txt'" error.

Do I need to create a requirements.txt file too? what goes in that?
version: 2

python:
install:
- requirements: docs/requirements.txt
- requirements: requirements.txt

I can't find anything that tells me what needs to be in the requirements.txt file... Anthony gave me 1:1 tutoring. I created a 1-line requirements file in the top level directory and tried the build again.

Manuel told me about fixing the config file and adding docs/source/conf.py

configuration: docs/source/conf.py

in yaml file have to readthe docs where the config file is.
And that did it! My build was successful.

[JeanSiegel]

I suggest an overview conceptual document that explains the configurations required for readthedocs and sphinx (and even mkbook) and how they interact. That would give me a mental model to trouble shoot if I wasn't sitting by an expert.

[humitos]

Thanks for your feedback on the tutorial! It's super valuable for us to have fresh eyes going over the whole tutorial 💯