Sphinx docs builds fail on readthedocs for private GitHub repository

Question

I have set up and built Sphinx docs (2.1.2) for a Python 3.6 project which is currently in a private GitHub repository. I want to host the docs on readthedocs.org after releasing the project publicly, but at the moment the readthedocs builds are always failing with this error message

 git clone --no-single-branch --depth 50 https://github.com/<user name>/<repo name> .

Cloning into '.'...
fatal: could not read Username for 'https://github.com': terminal prompts disabled

I've tried to look at the readthedocs project settings but I can't seem to find the right settings to modify to get the builds to work. The config. YAML was copied directly from the readthedocs template for Python projects.

# .readthedocs.yml
# 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:
  builder: html
  configuration: docs/conf.py
  fail_on_warning: false

# Build documentation with MkDocs
#mkdocs:
#  configuration: mkdocs.yml

# Optionally build your docs in additional formats such as PDF and ePub
formats: htmlzip

# Optionally set the version of Python and requirements required to build your docs
python:
   version: 3.6
   install:
      - requirements: docs/requirements.txt
      - requirements: requirements.txt
      - method: pip
   system_packages: true

This is docs/conf.py.

# Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# http://www.sphinx-doc.org/en/master/config

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
import os
import sys
sys.path.insert(0, os.path.abspath('.'))
sys.path.insert(0, os.path.abspath(os.pardir))


# -- Project information -----------------------------------------------------

project = '<project name>'
copyright = '2019, <author>'
author = '<author>'

# The full version, including alpha/beta/rc tags
release = '0.1.0'


# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [
    'recommonmark',
    'sphinx.ext.autodoc',
    'sphinxcontrib.httpdomain',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'sphinx.ext.coverage',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages'
]

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# The suffix(es) of source filenames.
# You can specify multiple suffix as a list of string:
#
source_suffix = ['.rst', '.md']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']

# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'

# If true, `todo` and `todoList` produce output, else they produce nothing.
todo_include_todos = True


# -- Options for HTML output -------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
#
html_theme = 'alabaster'

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']

# Example configuration for intersphinx: refer to the Python standard library.
intersphinx_mapping = {'https://docs.python.org/': None}

I don't think I missed anything - local Sphinx builds work, all the remote ones fail because of the clone error. It seems unable to clone via HTTPS. — mrs-qv7
If that were true, then none of the thousands of projects that are hosted on GitHub and get pulled into RTD would fail. Without further information about your configuration of RTD and your repo on GitHub, it's impossible to say what you missed. The rest of the Guide has more information on correct setup. There are more pages in the docs, if that one does not cover your issue. — Steve Piercy
Do you see that error above? Cloning into '.'... fatal: could not read Username for 'https://github.com': terminal prompts disabled. It has nothing do with the Sphinx configuration. Local Sphinx builds all work, and I can read the docs that I have built locally. — mrs-qv7
The GitHub repository is private. Coud that cause a problem for RTD? RTD configuration is standard: the repository URL is provided as https://github.com/<user name>/<repo name> — mrs-qv7

MasterOfTheHouse MasterOfTheHouse · Accepted Answer · 2020-02-18T19:49:52

This could happen because ReadTheDocs allows access to public repositories from its free membership.

However, for private GitHub repositories, we will have to use ReadtheDocs for Bussiness noted here

As of February 2020, the costs for each Plan are as under:

Plan:
 Advanced ($150 per month)

Plan Features:
Style your documentation to fit your company's brand
Support custom SSL certificates
Host documentation on your own domain

And

Plan: Basic ($50/month)

Plan Features: For hosting documentation for employees at your company

Hope this helps

Sphinx docs builds fail on readthedocs for private GitHub repository

1 Answers